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Preface 


IBM® Customer Information Control System (CICS®) Explorer is the new face of 
CICS Integration point for CICS tooling with rich CICS views, data, and methods. 

Are you looking for new ways to accelerate the transfer of knowledge, skills, and 
best practices to the next generation of technical staff and experts? Do you need 
to maintain productivity and protect service-levels? CICS Explorer™ and 
System z® lead the way to platform simplification. 

IBM CICS Explorer has a common, intuitive, Eclipse-based environment for 
architects, developers, administrators, system programmers, and operators. The 
task-oriented views provide integrated access to a broad range of data and 
control capabilities, and it also has powerful, context-sensitive resource editors. 
Integration point for CICS TS, CICS Tools, CICS TG, PD Tools, and Rational® 
Tools are extensible by independent software vendors (ISV), system integrators 
(SI), and customers who use our Software Development Kit. 

In this IBM Redbooks® publication, we focus on the new CICS Explorer. The first 
part of the book is an overview of the CICS Explorer along with all of the CICS 
Tools’ plug-ins. In the second part of the book, we focus on several scenarios in 
which you can use the CICS Explorer with the CICS Tools plug-ins to resolve 
various problems. 
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xiii 


© Copyright IBM Corp. 2010. All rights reserved. 



Nicholas Bingell is a Software Engineer in CICS Level II Technical Support at 
Research Triangle Park, NC. His areas of expertise isnclude CICS, CICS 
Explorer, and CICS Tools Interdependency Analyzer. He has a Bachelors degree 
in Software and Information Systems from The University of North Carolina at 
Charlotte. 

Gordon Keehn is an Advisory Software Engineer in the United States. He has 
18 years of experience in supporting CICSPlex® System manager. Before 
becoming involved with CICSPlex SM, he worked as an MVS System 
Programmer for several large corporations. He has a Bachelor of Arts degree in 
Chemistry from Hartwick College and a Master of Science degree in Organic 
Chemistry from the University of Pennsylvania. 

Lisa Fellows is the team manager of the Bank of America CICS and MQSeries® 
Technology Strategy group. Lisa has worked at Bank of America for 28 years, 
and supported CICS, including CICSPlex, since 1990. She has been a Deputy 
Project Manager for the SHARE CICS Project since 2001 . Lisa began presenting 
at SHARE in 2000 and is the recipient of multiple Best Session Awards. Her 
presentations cover a wide range of CICSPlex topics and recently include 
presentations about CICS Explorer. She currently works out of Clifton Park, New 
York, accessing emerging CICS and MQSeries technologies for a global Bank of 
America business partner demographic. 

Tommy Joergensen is a Senior IT Specialist working as a Tecnical Presales 
Specialist for System z software in IBM Nordic with a focus on the CICS TS and 
WebSphere portfolio. He has more than 25 years of experience working in CICS 
technical support, which includes three years at IBM Hursley and two years in the 
New Technology Center in Montpellier. Tommy participated in writing several IBM 
Redbooks publications in the CICS area, and delivers ITSO workshops around 
the world. 

Erhard Woerner is a Software Support Specialist in Germany. He has worked for 
IBM in CICS Level 2 Support for eleven years. He has 25 years of experience 
working with CICS in several roles. Before Erhard joined IBM, he worked as a 
CICS Systems Programmer at Deutsche Bank AG. He has excellent knowledge 
in the CICS programming languages COBOL, PL/I, and Assembler. He is an IBM 
Certifed Application Developer with IBM Enterprise PL/I. His areas of expertise 
include Virtual Storage Access Method (VSAM), CICS VSAM Recovery 
(CICSVR), CICS Web Services, and the z/OS® System Logger. 

Thanks to the following people for their contributions to this project: 

Richard M Conway 

International Technical Support Organization, Raleigh Center 
Thanks to the authors of the previous editions of this book. 


IBM CICS Explorer 



The authors of the first edition, IBM CICS Explorer, published in December 2009, 
were: 

Chris Baker, Diana Blair, Edoardo Comar, Stewart Francis, Em James, Chris 
Phillips, Kat Sharp, Pete Siddell, Colin Stone, Satish Tanna, Joe Winchester, Will 
Yates 


Now you can become a published author, too! 

Here's an opportunity to spotlight your skills, grow your career, and become a 
published author — all at the same time! Join an ITSO residency project and help 
write a book in your area of expertise, while honing your experience using 
leading-edge technologies. Your efforts will help to increase product acceptance 
and customer satisfaction, as you expand your network of technical contacts and 
relationships. Residencies run from two to six weeks in length, and you can 
participate either in person or as a remote resident working from your home 
base. 

Obtain more about the residency program, browse the residency index, and 
apply online at: 

i bin . com/redbooks/res i denci es . html 


Comments welcome 

Your comments are important to us! 

We want our books to be as helpful as possible. Send us your comments about 
this book or other IBM Redbooks publications in one of the following ways: 

► Use the online Contact us review Redbooks form found at: 
ibm.com/redbooks 

► Send your comments in an email to: 
redbooksQus . i bm.com 

► Mail your comments to: 

IBM Corporation, International Technical Support Organization 
Dept. HYTD Mail Station P099 
2455 South Road 
Poughkeepsie, NY 12601-5400 


Preface xv 


Stay connected to IBM Redbooks 


► Find us on Facebook: 
http://www.facebook.com/IBMRedbooks 

► Follow us on Twitter: 
http://twitter.com/ibmredbooks 

► Look for us on Linkedln: 

http : //www. 1 inkedin.com/groups?home=&gid=2 130806 

► Explore new Redbooks publications, residencies, and workshops with the 
IBM Redbooks weekly newsletter: 

https : //www. redbooks . i bm.com/Redbooks . nsf/subscri be?OpenForm 

► Stay current on recent Redbooks publications with RSS Feeds: 
http : //www . redbooks . i bm . com/rss . html 


xvi 


IBM CICS Explorer 


Summary of changes 


This section describes the technical changes made in this edition of the book and 
in previous editions. This edition might also include minor corrections and 
editorial changes that are not identified. 

Summary of Changes 
for SG24-7778-01 
for IBM CICS Explorer 

as created or updated on December 17, 2010. 


December 2010, Second Edition 

This revision reflects the addition, deletion, or modification of new and changed 
information described below. 

New information 

► Chapter 5, CICS Explorer navigation walkthrough 

► Chapter 9, CICS Explorer TG plug-in familiarization 

► Chapter 10, CICS Explorer Tivoli® OMEGAMON® XE plug in familiarization 

► Chapter 1 1 ,CICS Deployment Assistant 

► Chapter 12, WebSphere® MQ plug-in 

Changed information 

► Chapter 2 

► Chapter 3 

► Chapter 4 

► Chapter 13 


© Copyright IBM Corp. 2010. All rights reserved. 


xvii 





Part 1 


CICS Explorer 
Introductions 


In this part of the book, we look at the new CICS Explorer and introduce the 
following CICS Tools plug-ins. 

► CICS Explorer IA plug in 

► CICS Explorer CM plug-in 

► CICS Explorer PA plug-in 

► CICS Explorer WMQ plug-in 

► CICS Explorer Omegamon plug-in 

► CICS Deployment Assistant 
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CICS Explorer introduction 


In this chapter, we introduce the new Customer Information Control System 
(CICS) Explorer by giving you an overview before we introduce more basic 
capabilities. 
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1.1 Overview 


As a newcomer into a CICS environment or as an experienced user moving 
roles, CICS System Management can be a daunting challenge. Prior to the CICS 
Explorer, to perform each task could require the use of different disconnected 
interfaces. These applications were often ISPF-based panels and written to do a 
specific function, each of which required custom knowledge to operate. If the 
completion of a specific task crossed application boundaries, you had to switch 
back and forth between the applications, which each had its own commands and 
user interface. 

As well as basic CICS System Management, the definition and operation of 
regions and their installed resources, a typical CICS shop uses a number of 
tools, either obtained from IBM, third-party vendors, or developed in-house. 
These tools might have their own interfaces and way of presenting or 
manipulating the CICS runtime. 

Providing an integration platform so that all of the tools and applications that a 
user needs to perform a business task work together coherently in an integrated 
environment was one of the driving forces behind the creation of the CICS 
Explorer. The benefit of CICS Explorer is to help new users become familiar with 
the platform, to present a single and re-usable way of accessing and 
manipulating CICS to promote consistency, and to allow tools that are built by 
IBM, vendors, and customers alike to be able to extend and enhance in a unified 
way. Each tool must introduce its own value to CICS management without having 
to reinvent or redefine the interface to the base platform itself. 

As a system management tool the CICS Explorer is designed to be a scalable 
and intuitive way to manage a single CICS region, a collection of regions within a 
CICSplex, or a collection of CICSplexes. Experienced system programmers can 
quickly identify and tune their systems while newer users can be guided through 
the intuitive interface to learn how to perform standard tasks. By having a 
consolidated approach to system management, the number of interfaces that are 
required by CICS system administrators to learn to become effective is reduced, 
which helps to make the effort of attracting and training new developers and 
system programmers easier and less expensive. 

The CICS Explorer is based on the Eclipse Rich Client Platform (RCP). Eclipse 
RCP is a cross platform framework for building and deploying PC desktop 
applications. One of the features of Eclipse that makes it a good choice of 
technology for the CICS Explorer is its plug-in architecture, which allows different 
components to be added that can extend and complement each other. A number 
of plug-ins exist that can be integrated into Eclipse environments, such as 
workflow, messaging clients, or development tools. One of these products is IBM 
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Rational Developer for Z, which is an integrated development environment for the 
System z platform that allows the creation of programs that access the CICS API 
to perform transaction processing. By both products sharing Eclipse as their 
common base technology, the CICS Explorer integrates within IBM Rational 
Developer for System z version (version 7.5 or higher) to provide system 
administrative capabilities to CICS application developers. 

The CICS Explorer can be extended by plug-in providers using the Explorer API / 
SDK. Using the Explorer API / SDK customers can develop their own dedicated 
plug-ins to satisfy requirements particular to them. Using this framework 
maintains the consistency of the interface and integrates with the rest of the 
functionality that is provided in the Explorer and is the mechanism by which IBM 
and vendors provide plug-ins for their value-add tools. 

Figure 1-1 shows how CICS Explorer and Eclipse RCP platform fit together. 



At this point the CICS Explorer is not a full-functional replacement for the 
CICSPlex System Manager Web User Interface. Users who are comfortable with 
the Web user interface (WUI), or the more traditional CEMT and CEDA 
commands in CICS, can enjoy using them as before with the CICS Explorer 
providing a rich way to administer and perform operational tasks on CICS 
systems in a fashion that allows extension and customization by tools and 
third-party plug-ins. 


1.2 Base Explorer capabilities 

The CICS Explorer provides a base set of CICSPlex SM functions to manage 
CICS regions, resources, and definitions. It also provides a platform on which 
future CICS tools that are integrated in the Eclipse RCP can perform tasks and 
present the information in a common way. 
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CICS Explorer connects to either a CICSPlex SM WUI server or a single CICS 
region. The functions that are available depend on which version of CICS 
Transaction Server for z/OS you use. 

Figure 1-2 shows the different set ups. 



Figure 1-2 Different CICS setups 

When connected to a CICSPlex SM WUI server, CICS Explorer operations views 
provide a single-system image of all of the CICS resources within a CICSplex. 
When the CICS Explorer is connected to a CICS Transaction Server for z/OS 
Version 3 system, you can only browse the resources. However, when the CICS 
Explorer is connected to a CICS Transaction Server for z/OS version 4 CICSPlex 
SM WUI or a single CICS region, you can perform the following actions on 
operational resources: 

► Enable and disable resources 

► Open and close resources 


6 IBM CICS Explorer 


► Acquire and release resources 

► Place resources in and out of service 

► Purge tasks that are associated with a resource 

► Discard resource definitions from a CICS system where they are installed 

The CICS Explorer displays details of the CICS and CICSPlex SM resource 
definitions, and when the CICS Explorer is connected to a CICS Transaction 
Server for z/OS version 4 CICSPlex SM WUI, you can use the administration 
views and the resource editor to perform the following actions: 

► Create and update resource definitions 

► Install or remove resource definitions 

Administration operations are not supported in a single CICS region in the CICS 
Explorer version 1 .0. 

Table 1-1 to Table 1-3 on page 8 shows exactly what can you do with the 
Explorer, given a particular set up and CICS version. 


Table 1-1 Capabilities - CICSPlex SM CICS Version 4. 1 



Example 

Views 

Actions 

Operations 

Regions 

Large subset 
(40+) 

► Enable 

► Disable 

► Discard 

Administration 

(CSD 

Post-GA) 

Transaction 

Definitions 

All Basic 

► Create 

► Update 

► Install 

► Delete 

► Add/Remove 

Topology 

CICSPlex 

Subset 

No 

RTA Events 

RTA 

Outstanding 

Events 

Small subset 

No 

WLM 

Active 

Workloads 

Small subset 

No 

Monitoring 

Active Monitor 
Specifications 

N/A 

N/A 


Table 1-2 Capabilities - CICSPlex SM CICS Version 3 



Example 

Views 

Actions 

Operations 

Regions 

Large subset 
(40+) 

No 
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Example 

Views 

Actions 

Administration 
CICSPlex SM 
Only 

Transaction 

Definitions 

All Basic 

No 

Topology 

CICSPlex 

Subset 

No 

RTA Events 

RTA 

Outstanding 

Events 

Small subset 

No 

WLM 

Active 

Workloads 

Small subset 

No 

Monitoring 

Active Monitor 
Specifications 

N/A 

N/A 


Table 1-3 Capabilities - CICS Single Server CICS Version 4. 1 



Example 

Views 

Actions 

Operations 

Regions 

Large subset 
(40+) 

► Enable 

► Disable 

► Discard 

Administration 

(CSD 

Post-GA) 

Transaction 

Definitions 

All Basic 

► Create 

► Update 

► Install 

► Delete 

► Add/Remove 

Topology 

CICSPlex 

Subset 

N/A 

RTA Events 

N/A 

N/A 

N/A 

WLM 

N/A 

N/A 

N/A 

Monitoring 

N/A 

N/A 

N/A 


The CICS Explorer also displays Events and Active Workloads in a CICSPlex or 
single region and Properties for CICSPlex SM Objects. 

In addition, using the CICS Explorer you can define connections to multiple 
systems; however, only one connection can be active at a time. 

The CICS Explorer shows the CICSplexes, CICS systems, and regions for your 
current connection, the different system and resource groups, and their related 
resources. Using the CICS Explorer you can navigate to resources by selecting a 
context, and then resources are displayed in different tabular views depending on 
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their type. You can customize the attributes that display, enable filtering on 
attributes, select resources, and perform any appropriate actions. 

The CICS Explorer uses rich editors to display resource definition attributes in 
one or more pages. To simplify the update process for less-experienced CICS 
users, attributes are logically grouped together, and each attribute has more 
detail provided. Every attribute benefits from field-level verification, where the 
entry is validated in real time. Errors are identified by the Error icon, which 
identifies the field in error and the page on which the field appears. Additionally, 
the embedded help system can provide assistance for the entire editor or for a 
specific field, which allows you to quickly get the information that you require. 

To facilitate the move to CICS Explorer for experienced CICS users, one page in 
the rich editor, the Attributes page, displays the attributes in tabular form, 
grouped together in the same way that they appear in CEDA or in the CICSPlex 
SM WUI. For users on a CICS Version 3, system resource definitions are also 
displayed in this way; however, you cannot edit them. 

The CICS Explorer has an embedded help system to provide context and more 
detailed help for the resources and help about using the CICS Explorer and the 
basic Eclipse functions. More detailed help for CICS and CICSPlex SM is at the 
CICS Transaction Server for z/OS Information Center. 


1.3 Plug-ins and RCP 

The CICS Explorer is an Eclipse RCP-based GUI application that runs on the 
Microsoft® Windows® and Linux® operating systems. The user interface to the 
applications is through the workspace, which is a graphical multi-window 
environment that is built into Eclipse. The Eclipse platform is structured as 
subsystems that are implemented in one or more plug-ins. The subsystems are 
built on top of a small runtime engine. 

The workspace is a single window that consists of views and perspectives, and 
can contain other elements, such as editors, menus, and the help system. 

The CICS Explorer uses a subset of the Eclipse plug-ins to build its workspace. 
The CICS Explorer runs completely standalone, and no prior installation of 
Eclipse is required; however, it is necessary to understand some of the concepts 
from Eclipse to make full use of all that the Explorer offers. 

1.3.1 Eclipse concepts 

In this section, we discuss the concepts of Eclipse. 
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Perspectives overview 

A perspective is a layout of one or more views in the workspace. You can define 
your own perspectives to suit your particular needs. 

You can tailor a perspective by adding new views, removing existing views, 
moving views around, or changing the size of views. When you close CICS 
Explorer, any changes that you made to the perspective are saved, and the next 
time that CICS Explorer starts, your tailored perspective is displayed. This 
tailoring feature allows you to create a view of CICS that contains the set of 
resources that makes the most sense for a particular role and its tasks in your 
CICS environment. 

You can restore the default perspective at any time by going to the main 
workspace menu bar and clicking Window Reset Perspective. 

You can create and save multiple perspectives, for example, you might want to 
set up one perspective that only shows the administration views and one 
perspective that only shows the operation views. For further information about 
using perspectives, see the related links. 

When you save a perspective, you save only the layout of the views and editors in 
the workspace. If you change the width of a column in a view, that change is 
applied to that column in every perspective that contains the view. Any filter 
attributes that you set are retained when you switch to another perspective or 
view because a perspective is a definition of which views should be shown and 
their relative position, not their contents. The content is a property of the view 
that crosses perspective boundaries. The ability to create multiple instances of 
the same view with different filter or layout criteria might be included in a future 
release of the CICS Explorer, but it is not currently supported. 

The CICS Explorer comes with two built-in perspectives: 

► System Management 

The System Management perspective is the first perspective that is presented 
when the Welcome page closes on first startup of the CICS Explorer. It 
contains information about the currently connected CICS systems, which 
includes the active regions, the running tasks, and so forth. If there is no 
active CICS system connection, all of the views in the perspective are empty. 

► Resource 

The Resource perspective is the same perspective that is included with most 
Eclipse-based products and shows a set of files that are locally held on your 
computer file system. These files can be any file that you import into your 
Eclipse environment. In the CICS Explorer, the Resource perspective 
presents and allows manipulation of content that is typically destined for 
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deployment into an HFS folder that is associated with a CICS resource 
definition. 

Views overview 

Each perspective contains one of more views. A view is a visual component and 
provides a way to navigate the information in your workspace. 

The CICS Explorer uses some views that are provided with Eclipse itself, such as 
the Properties View, which shows attributes for a CICS resource or repository 
definition, and the Package view, which shows contents of a project for use in a 
CICS bundle. As well as using these existing Eclipse views, the CICS Explorer 
has a number of CICS-specific views that are arranged into a number of 
high-level conceptual categories. Views that display similar information are 
grouped together into tab groups. Each tab group is contained within a pane in 
the workspace window. 

Figure 1-3 provides an example of the Views. 
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Figure 1-3 Views overview 
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Navigation: Tab Group 1 

Using the CICSplex and CICSPlex Repositories view you can see a list of 
CICSplexes and active regions or CICSPlex repositories and defined definitional 
or system groups. 

Resources: Tab Group 2 

CICS Resources are divided into two categories: 

► Administration 

Administrative resources are those that reside in a repository, such as a CSD 
or CICSplex SM data repository (also known as BAS) and Transaction 
Definition or File Definition. Each CICS resource has a specific view. 

► Operational 

Operational resources represent live CICS resources that are installed into an 
active CICS region, such as tasks, programs, or files. 

If the view that shows a particular resource is not present in the perspective, 
open it by clicking Window ->• Show View and searching for the view by name. 
Alternately, use the pull-down menu Administration or Operational, and locate 
the appropriate view by resource name. In a CICS view, the pop-up menu shows 
a list of tasks that can be taken against the selected resource(s), one of which is 
open that activates an editor. We cover this topic more in “Editors overview” on 
page 13. 

The content of the resources views is scoped by the selected entry in one of the 
navigational views where appropriate. This scope is illustrated by the Tasks view, 
which shows all tasks for the selected sysplex, if one is selected in the CICSplex 
view. The Tasks view shows all tasks for the selected region if one is selected; 
likewise, for a view that shows CICS definitions, such as File Definitions, the 
scope of this is either all definitions for the selected CICSplex’s repository or for 
the selected resource definition group. 

Extended: Tab Group 3 

Using the CICS Explorer you can view additional details, such as CICS Plex SM 
system events or Real Time Analysis views. These details are arranged in the 
System Manager perspective at the bottom and are typically not scoped by the 
navigational views. This group also includes the Properties View, which shows all 
available attributes for a CICS resource. 

Help: Tab group 4 

You can open the help view in the perspective using function key 1 to show 
information from the documentation that is provided with the CICS Explorer. 


12 


IBM CICS Explorer 



Each view has a title, which is displayed in a tab at the top of the view. Where 
multiple views are present in a view set, they are stacked one behind the other. 
To activate a view, click its tab to bring the view to the front of the stack. The tab 
is highlighted, which indicates the active view. 

All views, with the exception of the CICSplex Explorer view, can be removed from 
view or moved to a different tab group, and each tab group can be sized or 
repositioned in the workspace. The CICSplex Explorer view is a special view that 
you cannot close or move. 

You can restore the default tab group arrangement (perspective) at any time by 
going to the main workspace menu bar and clicking Window ->• Reset 
Perspective. 

Editors overview 

An editor opens in a separate tab group called the editor area, which is 
positioned to the right of the tabular views. The editor area shares many features 
with the other tab groups, but it does have some limitations that we identify later 
in this topic. 

You open an editor from a resource definition view by right-clicking a resource, 
and then clicking Open. Figure 1-4 on page 14 shows the editor area, which is 
the active view. 
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The editor area appears to the right of the views. Each editor for a CICS resource 
has a tab that is labelled Attributes. Under the Attributes tab is a list of attributes 
that are arranged in a tree, which is designed to be familiar to users who are 
comfortable with CEDA or CEMT categorization. For some definitions there are 
additional tabs, such as the Overview tab for the pipeline definition, which 
arranges the information using rich controls to add description and grouping to 
help identify and explain the attributes and their contents. If the current 
connection is to a CICS Management Client Interface or CMCI connection, you 
can make changes to the definition through the editor and save the changes to 
update the CICS resource or definition. If the current connection is to a CICS 
Plex System Manager connection, the editor only allows viewing of the 
resource’s attributes. 
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Note: CMCI Connections are only available to regions running CICS 
Transaction Server Version 4.1 . 


You can minimize, maximize, or resize the editor area, but there are some 
limitations on moving the editor area and the editor. 

You change the size of the editor area in the same way that you size the other tab 
groups, but the editor area cannot be moved in the same way that you move the 
other tab groups. To reposition the editor area in the workspace, move the other 
tab groups around the editor area, for example, to reposition the editor area more 
to the middle of the workspace, drag the tabular views tab group, and drop it at 
the right side of the editor group, as shown in Figure 1-5. 



Figure 1-5 Editor, changing the size 


If you open more than one instance of the editor, you can move the views around 
in the editor area, for example, you can position them one above the other or 
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side-by-side, as shown in Figure 1-6, but you cannot move the editor instances 
into a different tab group. 



Figure 1-6 Moving the views around 

If you reset the perspective, the perspective is restored to the default layout; 
however, any open editors are unchanged and remain in the workspace. 
Similarly, if you change to another perspective, any open editors remain visible in 
the new perspective. 

Embedded help system 

Using the embedded help system you can browse, search, and print system 
documentation. The help system also provides a context-sensitive help, which 
you can access by pressing the ‘FI’ hotkey (Windows) or CNTRL-F1 (Linux). 
This help system gives an overview of the resource with which you are working 
and a text search capability for finding the information that you need, by keyword. 
The help is displayed either in a Help view in the workspace, in a separate Help 
Contents window, or in an external browser window. 
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The CICS Explorer includes detailed help information for CICS resources and 
their attributes that is sensitive to where it is activated from. In the Properties 
View or the attributes tab of an editor, when an individual attribute is selected and 
FI pressed to activate help, the help contents shown are specific to the selected 
attribute. In some views, such as the customize columns dialog for a CICS 
resource view or a CICS definition creation wizard, activating help opens the help 
contents in the active window, again showing contents that are applicable to the 
selected or currently focused attribute. 
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Getting started with CICS 
Explorer 

In this chapter, we describe the steps that are required to implement CICS 
Explorer for those who want to execute independently-managed CICS regions 
(the single system set up) and for those who want to use CICSPlex SM to enable 
you to take advantage of CICS Explorer. 


© Copyright IBM Corp. 2010. All rights reserved. 
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2.1 Using CICS Explorer with CICS TS 4.1 


CICS TS 4.1 introduces a new facility called the CICS Management Client 
Interface (CMCI). This interface is exploited by CICS Explorer to provide Create, 
Read, Update, and Delete capabilities. 

In this section, we tell you how to use CICS Explorer with CICS TS 4.1 . 


2.2 CICS Explorer connection to CICS 

CICS Explorer operates in two distinct ways: 

► Connected to a CICS region 

► Connected to CICSPlex SM 


2.2.1 Connecting CICS Explorer to a CICS region 

Small-scale users can connect CICS Explorer directly to individual CICS regions, 
which provides access to basic operational capabilities and resources definitions 
through the CSD, as shown in Figure 2-1 on page 21. Small enterprises can 
therefore benefit from a modern-management interface and integration with the 
CICS tools. Set up is minimal requiring only a few minutes with CMCI initializing 
the first time a request is made to the region. All that is required to gain access is 
a TCP/IP Service definition and the addition of the appropriate Library. 

This type of usage scenario is described as a System Managed Single Server or 
SMSS. This term is also sometimes referred to as Single Server. 

CICS Explorer lets you work with the resources on just this single system. The 
SMSS capabilities of CICS cannot be used if the CICS is managed by CICSPlex 
SM. 


20 IBM CICS Explorer 



Single Server Management Interface 


| SMAPI 



Request ~| 


CICS 


| PC Based Client | 




Figure 2-1 Connected to a CICS region 

If you have multiple CICS regions, each region requires a TCP/IP Connection 
and you must connect CICS Explorer to each CICS, in turn, to work with it. 


For those who exploit the extensive capabilities that CICSPlex SM provides, you 
can use CICS Explorer to access the CICSPlex SM environment, as shown in 
Figure 2-2 on page 22. In contrast to the previous support pack edition, this 
interface now gives you the ability to take actions on resources. Establishing 
access requires, again, a simple set of actions, even for a first time CICSPlex SM 
user. For existing CICSPlex SM users, access is virtually immediate. 

If the system is managed by CICSPlex SM, you cannot use the CICS SMSS / 
Single Server capabilities. 


2.2.2 Connecting CICS Explorer to CICSPlex SM 
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CICSPlex SM Configuration 


| Request | 


Response 

| PC Based Client | 


Figure 2-2 Connected to CICSPlex SM 




As users migrate to the advanced facilities of CICSPlex SM, the CICS Explorer 
experience expands into this new set of capabilities, eliminating the relearning 
curve that often occurs when introducing new management tools. 


2.3 Setting up single-server access 

To set up a single server to access CICS Explorer: 

1 . Copy the IBM-supplied group DFH$WU to a user-defined group. You need 
one group for each CICS system that you want to manage. 

2. In your user-defined group, update TCPIPService definition DFH$WUTC and 
the Portnumber (each CICS requires a unique value for the TCP/IP Stack 
being used). If the CICS is running with security (SEC=YES in the SIT), 
change Authenticate to Basic. 

3. Install the user-defined group (URIMAP definition DFH$WUUR is installed 
alongside the DFH$WUTC.TCPIPSERVICE). 

4. Add the CICS TS SEYULOAD data set to the CICS DFHRPL concatenation 
and the CICS TS SEYUAUTH data set to the STEPLIB concatenation in the 
CICS JCL. (Make sure that the CICS TS SEYUAUTH data set is APF 
authorized). 

Example 2-1 on page 23 shows a JCL that needs updating, and Example 2-2 on 

page 23 shows an updated JCL. 
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Example 2- 1 Update the CICS JCL (before update) 


//CICS EXEC PGM=DFHSIP,REGI0N=240M, 

// PARM= ( 1 SIT=6$ 1 , 

// ' START=AUTO,SI ' ) 

//SYSIN DD * 

GRPLIST=(DFHLIST,userl istl.userl ist2) , 

APPLID=CICSHTH1 , 

.END 

//STEPLIB DD DSN=CICSTS41.CICS.SDFHAUTH,DISP=SHR 
// DD DSN=CICSTS41.CICS.SDFJAUTH,DISP=SHR 

//DFHRPL DD DSN=CICSTS41.CICS.SDFHL0AD,DISP=SHR 
// DD DSN=your. prog. library, DISP=SHR 

// DD DSN=your. table. 1 ibrary,DISP=SHR 

//DFHCSD DD DSN=CICSTS41.CICS.DFHCSD,DISP=SHR 


Example 2-2 Updated JCL 

//CICS EXEC PGM=DFHSIP,REGION=OK, 

// PARM= ( ' SIT=6$ 1 , 

// ' START=AUTO,SI ' ) 

//SYSIN DD * 

GRPLIST=(DFHLIST,userl istl.userl ist2) , 

APPLID=CICSHTH1 , 

.END 

//STEPLIB DD DSN=CICSTS41.CPSM.SEYUAUTH,DISP=SHR 
// DD DSN=CICSTS41.CICS.SDFHAUTH,DISP=SHR 

// DD DSN=CICSTS41.CICS.SDFJAUTH,DISP=SHR 

//DFHRPL DD DSN=CICSTS41.CPSM.SEYUL0AD.DISP=SHR 
// DD DSN=CICSTS41.CICS.SDFHL0AD,DISP=SHR 

// DD DSN=your. prog. library, DISP=SHR 

// DD DSN=your. table. 1 ibrary,DISP=SHR 

//DFHCSD DD DSN=CICSTS41. CICS. DFHCSD, DISP=SHR 


Figure 2-3 on page 24 shows the Explorer connection to a single server. The 
Connection type to specify is CICS Management Interface. The Server address 
to use is the IP address of the TCP/IP stack that the CICS will use, and the 
Portnumber corresponds to the port number that is specified on the DFHEWUTC 
tcpipservice that you installed. The interface initializes when the CICS region 
receives the first request. 
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Figure 2-3 Explorer connecting to a single server 

Before a Connection can be created at least one Credential must exist, 

Figure 2-4 on page 25 shows the Credentials Preferences window where you 
define the UserlD and Password pair to be used by the Connections profiles that 
you create. 


24 


IBM CICS Explorer 



Figure 2-4 Credentials Preferences window 


2.4 Setting up CICSPlex SM for CICS Explorer 

In this section, we describe the steps that are required to set up CICSPlex SM to 
take advantage of CICS Explorer. 


2.4.1 Basics of setting up CICSPlex SM for CICS Explorer 

To set up CICSPlex SM, you need two new CICS systems. In this document, we 
turn one of these systems into a CMAS and the second into a Web User 
Interface (WUI) server. 

A CMAS is a CICS system that manages a CICSplex. It is a dedicated system; 
therefore, no other workloads run inside it. 

A CICSplex is a set of CICS systems that CICSPlex SM manages. You might 
have a number of CICSplexes in your enterprise, but an individual CICS system 
can only belong to (be managed by) one CICSplex. 
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A WUI server is a CICS system that acts as a Web server for the Web User 
Interface into CICSPlex SM. If you use the CICS Explorer with CICS TS 4.1 the 
Explorer uses this to acquire information about your CICS systems and 
resources. This is a dedicated system, so no other workloads run inside it. 

As a first step, create two new CICS systems. Figure 2-5 shows an example of 
our environment. The assumptions that we made are: 

► CICS systems are on a single LPAR 

► CICSPlex SM Libraries are downloaded 

► You have JCL for existing CICS regions 



Figure 2-6 on page 27 shows our environment plus WUI and CMAS regions. 
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Create two new CICS regions (CMAS and WUI server) 


CICS1 

CICS5 

□ 

CICS4 

□ 

CICS2 

CICS3 

1 — 1 


[J 


► Use your existing CICS JCL, etc. 


JCL for CICS Regions 


Figure 2-6 Existing setup plus WUI and CMAS regions 


2.4.2 Changing a System into a CMAS 

Figure 2-7 on page 28 shows an example of creating a CMAS Repository. 
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Creating a data repository 

To change one of your systems into a CMAS you must first create and initialize a 
data repository. A data repository is a VSAM file that CICSPlex SM uses to store 
definitions, which is a bit like a CICS CSD. Example 2-3 shows sample syntax for 
creating a data repository, and Example 2-4 on page 29 provides sample JCL 
syntax to initialize the repository. 

Example 2-3 Create the CMAS repository 

//DEFDREP EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=* 

//SYSIN DD * 

DEFINE CLUSTER - 
(NAME(@newdrep@) - 
RECORDS (500, 3000) - 
V0LUME(@dsvol@) - 
CISZ (8192) - 
RECSZ(200,6550) - 
KEYS(64,0) - 
SHR(2) - 
INDEXED - 
SPEED - 
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REUSE) 


/* 


Example 2-4 Initialize the repository 

//DREPINIT EXEC PGM=EYU9XDUT, 

1 1 C0ND=(8,LT) , 

1 1 PARM= ( 1 CMASNAME=@cmasname@ 1 , 

1 1 ' DAYLIGHT=N 1 , 

1 1 1 TIMEZONE=@tirnezone@ 1 , 

// 'SYSID=@cmssysid@' , 

// 1 Z0NE0FFSET=0') 

//EYUXDPRM DD * 

WUI=YES 

WUI PLEX=WUI PLEX1 
WUINAME=@wuiname@ 

WUIAPPLID=@wui appl id@ 

WUISYSID=@wui sysid@ 

/* 

//STEPLIB DD DISP=SHR,DSN=@cpsmhl qQ.SEYUAUTH 
/ / EYUDREP DD DISP=OLD, DSN=@newdrep@ 
//SYSPRINT DD SYSOUT=* 


There are two variables that you must specify in the JCL for creating the 
repository (Example 2-3 on page 28): 

► The data set name (@newdrep@) that you want the repository to have (make 
a note of this name, you will need it later) 

► The volume (@dsvol@) on which you want the data set created 

Initializing the data repository 

Next, we must initialize the data repository, which loads the repository with some 
definitions that are needed for the CICSPlex to work. Example 2-4 contains some 
sample JCL to initialize the data repository. 

There are a number of variables that you must set in the JCL. Let us start with 
the simplest: 

1 . Where @cpsmhlq@ appears, enter in the High Level Qualifier for the release 
of CICS TS that you are working on, for example: 

CTS41 0.CPSM.SEYUAUTH. 

2. Populate @newdrep@, which this is the name that you gave to your Data 
Repository when you created it with IDCAMS, as shown in Example 2-3 on 
page 28. 
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3. Populate the @cmasname@ variable. This entry is simply a name that 
CICSPlex SM uses to identify the CMAS. You can use up to eight characters 
(A-Z and 0-9) for the name. You might want to use the APPLID of the system 
as a name for simplicity. Make a note of the CMAS name because you will 
need it later. 

4. Set @timezone@ to the letter A to use your local timezone. 

5. Set @cmssysid@, which is the system ID of the CICS system that you are 
turning into a CMAS: 

a. Find the SYSIDNT SIT parameter in your CICS JCL, and copy its value 
into this variable. If you do not have a SYSIDNT SIT parameter, create a 
four character identifier. The last four characters of the system's APPLID 
can be used for this. The value must be unique. 

The next set of variables help define a CICSplex for your WUI server and tell the 

CMAS a bit about the CICS system that you are using as a WUI server: 

► @wuiapplid@ is the APPLID of the CICS system that you are turning into a 
WUI server. This is not the same system that you are turning into a CMAS. In 
your CICS JCL, find the APPLID SIT parameter, and copy its value into the 
@wuiapplid@ variable. 

► @wuisysid@ is the system ID of the CICS system that you are turning into a 
WUI server. This is not the same system that you are turning into a CMAS. In 
your CICS JCL, find the SYSIDNT SIT parameter, and copy its value into the 
@wuisysid@ variable. If you do not have a SYSIDNT SIT parameter, you 
must create a four character identifier. Use the last four characters of the 
system's APPLID. This value must be unique. 

► @wuiname@ is a name that CICSPlex SM uses to identify the WUI server. 
You can use up to eight characters (A-Z and 0-9) for the name. You can use 
the APPLID of the system as a name. Make a note of the name because you 
will need it later. 


Note: There is also a parameter called WUIPLEX that, in this example, 
was set to WUIPLEX1 because the WUI is managed inside of its own 
CICSplex. For this exercise, it is not important to understand why this is the 
case, so it is fine to just use the WUIPLEX1 value. 


Both the data repository creation and initialization can be JOBSTEPS inside a 
single JOB. 

When the JCL is submitted, you will get a return code of 0, which means that 
your data repository data set is created and initialized. 


30 


IBM CICS Explorer 




Modifying the CICS JCL 

Now we must modify the JCL of the CICS system that we are turning into a 
CMAS. Example 2-5 shows a CMAS JCL before modification. 

Example 2-5 Update CMAS JCL (before) 

//CICS EXEC PGM=DFHSIP,REGI0N=240M, 

// PARM= ( ' SIT=6$ ' , 

// ' START=AUTO,SI ' ) 

//SYSIN DD * 

GRPLIST=(DFHLIST,userl istl.userl ist2) , 

APPLID=CICSHTH1 , 

.END 

//STEPLIB DD DSN=CICSTS41.CICS.SDFHAUTH,DISP=SHR 
// DD DSN=CICSTS41.CICS.SDFJAUTH,DISP=SHR 

//DFHRPL DD DSN=CICSTS41.CICS.SDFHL0AD,DISP=SHR 
// DD DSN=your. prog. library, DISP=SHR 

// DD DSN=your. table. 1 ibrary,DISP=SHR 

//DFHCSD DD DSN=CICSTS41.CICS.DFHCSD,DISP=SHR 


Example shows the JCL after modification. 

Example 2-6 Update CMAS JCL (after) 

//CICS EXEC PGM=EYU9XECS,REGI0N=0K, 

// PARM=( 1 SIT=6$ 1 , 

// 1 START=AUTO,SI ' ) 

//SYSIN DD * 

GRPLIST=(DFHLIST,userl istl.userl ist2) , 

APPLID=CICSHTH1 , 

MXT=300, 

CPSMCONN=CMAS, 

EDSALIMIT=100M, 

ICVR=20000, 

SEC=N0, You can switch it on later 

SP00L=YES, 

WRKAREA=2048, 

.END 

//STEPLIB DD DSN=@cpsmhl q@.SEYUAUTH,DISP=SHR 
// DD DSN=CICSTS41.CICS.SDFHAUTH,DISP=SHR 

// DD DSN=CICSTS41.CICS.SDFJAUTH,DISP=SHR 

//DFHRPL DD DSN=@cpsmhlq@.SEYULOAD.DISP=SHR 
// DD DSN=CICSTS41.CICS.SDFHL0AD,DISP=SHR 
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// DD DSN=your. prog. library, DISP=SHR 

1 1 DD DSN=your. table. 1 ibrary,DISP=SHR 

//DFHCSD DD DSN=CICSTS41.CICS.DFHCSD,DISP=SHR 
//EYUDREP DD DISP=SHR,DSN=@newdrep@ 

//EYUPARM DD * 

NAME(@cmasname@) 

SEC(NO) 

/* 


To modify the JCL: 

1 . In the JOBSTEP for the CICS system, change the program from DFHSIP to 
EYU9XECS. Also, add REGI0N=0K to this line. 

2. Add the following data set to your STEPLIB (as before, the variables used 
depend on the release of CICS TS that you are using): 
@cpsmhlq@.SEYUAUTH 

3. Add the following data set to DFHRPL: 

@cpsmhlq@.SEYULOAD 

4. Add the following SIT parameter: 

CPSMCONN=CMAS 

5. Add or change the MXT SIT parameter, which is the minimum MAXTASKs 
value for a CMAS. (For a basic set up, 300 is an appropriate value): 
MXT=300 

6. Change the EDSALIMIT SIT parameter, which is the minimum DSA size for a 
CMAS. (For a basic set up this is an appropriate value): 

EDSALIMIT=100M 

7. Add or change the ICVR SIT parameter: 

ICVR=20000 

8. Add or change the SEC SIT parameter. Initially we run with security off. You 
can run with security on at a later date: 

SEC=NO 

9. Add or change the SPOOL SIT parameter: 

SPOOL=YES 

10. Reserve 2048 bytes for the Common Work Area (CWA): 

W R KA R E A=2048 
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1 1 .Change the START SIT parameter: 

START=AUTO 

You might want to force a COLD/INITIAL start on the first startup, but an 
AUTO restart is fine after that. 

12. Add the following DD card to the JCL, where @newdrep@ is the name of the 
Data Repository that you created earlier: 

//EYUDREP DD DISP=SHR,DSN=@newdrep@ 

13. Add the following DD card: 

//EYUPARM DD* 

NAME(@cmasname@) 

SEC(NO) 

/* 

The example here assumes that the IBM supplied SIT 6$ is used. If you use 
an installation-defined SIT, you might need to modify other values that are not 
shown here; otherwise, incorrect results can occur. 

Example on page 31 is an example of all of these changes. You are now ready 
to start your CMAS. 

Starting the CMAS 

Submit the JCL you just modified. If the CMAS starts successfully, in the logs, 
you will see the following messages: 

► EYUXL0007I IYK3ZDD1 CMAS Phase III initialization complete. 

► EYUXL0007I IYK3ZDD1 CMAS Phase IV initialization complete. 

► EYUXL0010I IYK3ZDD1 CMAS initialization complete. 

If CMAS initialization does not complete, go back and make sure that all of the 
names, APPLIDs, and system IDs that you defined are correct. 

2.4.3 Changing a system into a Will server 

The first step to creating a WUI server is to create a WUI repository, as shown in 
Figure 2-8 on page 34. 
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Create WUI repository 



Figure 2-8 Create a WUI repository 


The WUI repository is a VSAM data set that holds all of the Views and Menus 
that the WUI serves to a browser. Example 2-7 contains some sample JCL to 
create a WUI repository. 

Example 2-7 Create WUI repository 

//DEFWREP EXEC PGM=IDCAMS 
//SYSPRINT DD SYS0UT=* 

//SYSIN DD * 

DEFINE CLUSTER ( 

NAME(@newwuirep@) - 
VOLUME(@dsvol@) 

ST0RCLAS( STANDARD ) 

RECORDS ( 5000 5000 ) 

C0NTR0LINTERVALSIZE( 8192 ) 

SPANNED 

INDEXED 

SHARE0PTI0NS( 2 ) 

) 

DATA ( 

NAME (Onewwui rep0.DAT A ) - 
KEYS( 20 20 ) 
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RECORDS IZE ( 8192 32000 ) 


) 

INDEX ( 

NAME(@newwuirep@. INDEX ) - 


/* 


The data set name that you want the WUI repository to have is @newwuirep@. 
We are now ready to modify our CICS system's JCL to turn it into a WUI server. 

Modifying the CICS JCL 

Example 2-8 shows the changes to make to CICS JCL to make it a WUI server. 
Example 2-8 Change CICS JCL to make it a WUI 
//CICS EXEC PGM=DFHSIP,REGI0N=0K, 

1 1 PARM=( 1 SIT=6$ 1 , 

// 1 START=AUT0,SI 1 ) 

//SYSIN DD * 

GRPLIST=(DFHLIST) , 

APPLID=CICSHTH1 , 

CPSMC0NN=WUI 

INITPARM=(EYU9VWAN =< ENU1 ’ , EYU9VKEC=‘ ENU’) , 

EDSALIM=100M, 

MXT=120, 

TCPIP=YES, 

SEC=N0, You can switch it on later 

WRKAREA=2048, 

CWAKEY=CICS, 

.END 

/* 

//STEPLIB DD DSN=@cpsmhl q@.SEYUAUTH,DISP=SHR 
// DD DSN=CICSTS41.CICS.SDFHAUTH,DISP=SHR 

// DD DSN=CICSTS41.CICS.SDFJAUTH,DISP=SHR 

//DFHRPL DD DSN=@cpsmhlq@.SEYULOAD.DISP=SHR 
// DD DSN=CICSTS41.CICS.SDFHL0AD,DISP=SHR 

// DD DSN=your. prog. library, DISP=SHR 

// DD DSN=your. table. 1 ibrary,DISP=SHR 

//DFHCSD DD DSN=CICSTS41.CICS.DFHCSD,DISP=SHR 

//EYUWREP DD DISP=SHR,DSN=@newdrep@ 

//EYUPARM DD * 

NAME(@wuiname@) 

CICSPLEX(WUIPLEXl) 
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CMASSYSID(@cmassysid@) 

SEC(NO) 

/* 

//EYUWUI DD * 
TCPIPHOSTNAME(@hostname@) 
TCPIPPORT (@portnumber@) 
DEFAULTCONTXT (@mai nl ex@) 
DEFAULTSCOPE(@mai npl ex@) 
DEFAULTCMASCTXT (@cmasname@) 
AUTOIMPORTDSN(@cpsmhlq@.SEYUVIEW) 
AUTOIMPORTMEM(EYUEA*) 
CMPIPORT=@portnumber@ 

/* 


Now we must modify the JCL of the CICS system that we are turning into a WUI 
server: 

1 . Add the following data set to your STEPLIB (as before, the variables that are 
used depend on the release of CICS TS that you are using): 
@cpsmhlq@.SEYUAUTH 

2. Add the following data set to DFHRPL: 

@cpsmhlq@.SEYULOAD 

3. Add the following SIT parameter: 
INITPARM=(EYU9VWAN='ENU1',EYU9VKEC='ENU') 

4. Reserve 2048 bytes of CICS key storage for the Common Work Area (CWA): 
W R KA R E A=2048 

CWAKEY=CICS 

5. Make sure that the TCPIP SIT parameter is set to YES and that the CICS 
system can run as a Web server. 

6. Add the following DD card: 

//EYUPARM DD* 

NAME(@wuiname@) 

CICSPLEX(WUIPLEXI) 

CM ASS YS I D( @ cmssysid @ ) 

SEC(NO) 


IBM CICS Explorer 



Note: @wuiname@ must match the WUI name you specified when 
creating the CM AS Data Repository. @cmssysid@ must match the 
system ID of the CMAS, not the WUI server system ID. 


//E YU WUI DD* 

TCPIPHOSTNAME( @ hostname @) 

TCPIPPORT(@portnumber@) 

DE FAU LTCM ASCTXT( @cmasname@) 

DEFAULTCONTEXT(@mainplex@) 

DEFAULTSCOPE(@mainplex@) 

AUTOIMPORTDSN(@cpsmhlq@.SEYUVIEW) 

AUTOIMPORTMEM(EYUEA*) 

CMPIPORT(@cmciportnumber@) 

► @hostname@ is the TCP/IP host name for the IP stack that CICS will use. 
This value is also used when configuring the connection to this WUI server in 
CICS Explorer. 

► @portnumber@ is a port number that was allocated for the use of the WUI 
server. This value is used by web browser users. 

► @cmasname@ is the name of the CMAS you are connecting to (for example, 
the name of the CMAS that you created earlier). 

► @mainplex@ is the name of the CICSplex to which you must add your 
existing CICS systems. It can be any eight-character string (A-Z and 0-9). You 
will create this CICSplex later. In this example, we use a CICSplex name of 
TESTPLEX, so in our WUIPARM we will have: 
DEFAULTCONTEXT(TESTPLEX) 

DEFAULTSCOPE(TESTPLEX) 

► @cpsmhlq@ is the High Level Qualifier for the release of CICS TS that you 
are working on, for example: CICSTS41 .CPSM.SEYUVIEW. 

► @CMCIPORTNUMBER@ is the port number that is allocated for the use of 
the CICS Management Client interface for this WUI server. This value must 
not be the same as the value specified in @portnumber@. This value is used 
when configuring the connection to this WUI server on a CICS Management 
Interface connection in CICS Explorer. 

Example 2-8 on page 35 is an example of all of these changes. You are now 

ready to start the WUI server. 
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Starting the Will Server 

Submit the JCL you just modified. If the WUI starts successfully, in the system 
log you will see messages similar to the following messages: 

EYUXL0030I IYK3ZDD4 ESSS connection in progress to CICSPLEX (WUI PLEX1) 
for SYSID(@cmssysid@) 

EYUXL0004I IYK3ZDD4 ESSS connection complete. 

EYUCL0006I IYK3ZDD4 ESSS link to IYK3ZDD1 established. 

EYUXL0007I IYK3ZDD4 LMAS Phase II initialization complete. 

EYUNL0099I IYK3ZDD4 LMAS LRT initialization complete. 

At the top of the EYULOG you will see messages similar to the following 
messages. There will also be additional messages after these, but do not worry 
about them because they mostly relate to the WUI loading the Views and Menus 
that it is going to use: 

EYUVS0101I IYK3ZDD4 Parameter service initialization complete. 

EYUVS0200I IYK3ZDD4 Starting CICS Web Interface. 

EYUVS0204I IYK3ZDD4 TCP/IP service (EYUWUI) installed successfully. 
EYUVS0206I IYK3ZDD4 CICS Web Interface enabled on TCP/IP port number 
@portnumber@. 

EYUVS0204I IYK3ZDD4TCP/IPservice (EYUCMCIT) instal 1 ed successful ly. 
EYUVS0209I IYK3ZDD4 URI map (EYUCMCIU) instal led successful ly. 

EYUVS021 1 I IYK3ZDD4 CICS Management Client Interface enabled on TCP/IP 
port number @cmci portnumber@. 

EYUVS0002I IYK3ZDD4 CICSPlex SM Web User Interface initialization 
complete. 

EYUVS0010I IYK3ZDD4 Server connected to CMAS, SYSID(@cmssysid@) . 

If WUI initialization does not complete, go back and make sure that all of the 
names, APPLIDs, and system IDs that you defined are correct. 

You are now ready to create a CICSplex for all of the CICS systems that you want 
to manage. 


2.4.4 Creating a CICSplex to manage your systems 

We are now going to define a CICSplex that will be used to manage your existing 
CICS systems. We also define your CICS systems to the CICSplex, so that when 
you start those systems, CICSPlex SM knows which CICSplex they are being 
managed by. Example 2-9 on page 39 shows a sample JCL for creating the 
CICSplex and defining your CICS systems. 
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Example 2-9 Sample JCL to create CICSplex 


//CPSMDEFN 

EXEC 

PGM=EYU9XDBT 

//* 

//STEPLIB 

DD 

DISP=SHR,DSN=@cpsmhl qQ.SEYULOAD 

// 

DD 

DISP=SHR,DSN=@cpsmhl q@.SEYUAUTH 

//* 

//SYSTSPRT 

DD 

SYS0UT=* 

//EYUTRCF 

DD 

SYS0UT=* 

//* 

//EYUCPDEF 

DD 

DISP=SHR,DSN=@cpsmhl q@.SEYUPARM( EYUCPDEF) 

//EYUCSDEF 

DD 

DISP=SHR,DSN=@cpsmhl q@.SEYUPARM( EYUCSDEF) 

//EYUCSGRP 

DD 

DISP=SHR,DSN=@cpsmhl q@.SEYUPARM( EYUCSGRP) 

//* 

//EYUSYSIN 

DD 

DDNAME=SYSIN 


* Set CONTEXT to CMAS 


CONTEXT @cmasname@ 

* Define the CICSplex 
DEFINE CICSPLEX @plexname@ 

* Set CONTEXT to the CICSplex 
CONTEXT @plexname@ 

* Define a CICS region 

DEFINE REGION @systemname@ - 

APPLID Osystemappl id@ - 

SYSID @systemsysid@ - 

CMAS ID @cmasname@ 


To create a CICSPlex that manages your systems: 

1 . @cpsmhlq@ is the High Level Qualifier for the release of CICS TS that you 
are working on, for example: CICSTS41.CPSM. 

2. @cmasname@ is the name of the CMAS you are connecting to (for example, 
the name of the CMAS that you created earlier). 

3. @plexname@ is the name of the CICSplex that is going to manage your 
systems, which is any name up to eight characters long (A-Z and 0-9). For 
this example, TESTPLEX is a valid name to enter here. 

4. @systemapplid@ is the APPLID of a CICS system that you want to manage 
in your CICSplex. Find the APPLID SIT parameter in the JCL for the system 
you want to manage, and copy its value into this variable. 

5. @systemsysid@ is the system ID of the CICS system that you want to 
manage in your CICSplex. Find the SYSIDNT SIT parameter in your CICS 
JCL, and copy its value into this variable. If you do not have a SYSIDNT SIT 
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parameter, create a four-character identifier. The last four characters of the 
system's APPLID can be used for this. This value must be unique. 

6. @systemname@ is simply a name that CICSPlex SM uses to identify the 
system. You can use up to eight characters (A-Z and 0-9) for the name, and 
you can use the APPLID of the system as a name. Make a note of the name 
because you will need it later. 

7. Repeat the DEFINE REGION statement for every CICS system that you want 
to manage in your new CICSplex. Do not forget to change that variable to 
match the APPLID of each system. 

8. Submit the job, which causes all of your new definitions to be created. 

You are almost ready to manage your CICS systems through CICSPlex SM. The 
last step before starting your systems is to alter the JCL of your CICS systems to 
allow them to connect to CICSplex SM. 

2.4.5 Modifying your existing CICS system JCL 

Take the JCL that you have for an existing CICS system that you want to be 
managed by CICSPlex SM, and make the following modifications to it: 

1 . Add the following data set to your STEPLIB (as before the variables used 
depend on the release of CICS TS that you are using: 
@cpsmhlq@.SEYUAUTH 

2. Add the following to DFHRPL: 

@cpsmhlq@.SEYULOAD 

3. Add the following SIT parameter: 

CPSMCONN=LMAS 

4. Add or change the SEC SIT parameter (you can turn on security at a later 
date): 

SEC=NO 

5. Add the following DD card: 

//EYUPARM DD* 

NAME(@cicsname@) 

CICSPLEX( @ plexname @ ) 

CM ASS YS I D( @ cmssysid @ ) 

The variable @cicsname@ is the name of the CICS system that we defined in 
the WUI, which must match the name defined in the WUI; otherwise, the system 
will not connect to the CICSplex. In our example, our system names are the 
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same as our systems' APPLIDs. The variable @plexname@ is the name of the 
CICSplex that we created in the WUI; however, in our example, this was 
TESTPLEX. The variable @cmssysidcmssysid@ is the system ID of the CICS 
system that is acting as out CMAS. 

After you make these changes, submit your JCL, and start your managed CICS 
system. If the CICS system successfully connects to the CICSplex, you will see 
the following messages in the system log: 

EYUXL0030I IYK3ZDD4 ESSS connection in progress to CICSPLEX (DWDPLEX1) 
for SYS ID (DANA) . 

EYUXL0004I IYK3ZDD4 ESSS connection complete. 

EYUCL0006I IYK3ZDD4 ESSS link to IYK3ZDD1 established. 

EYUXL0007I IYK3ZDD4 LMAS Phase II initialization complete. 

EYUNL0099I IYK3ZDD4 LMAS LRT initialization complete. 

If the connection to the CICSplex fails, check that the NAME in the EYUPARM in 
your JCL matches the CICS system definition name for the definition you defined 
through the WUI. 

Repeat this step for all of the CICS systems that you want CICSPlex SM to 
manage. 


2.4.6 Conclusion 

To set up CICSplex SM, you: 

1 . Turned a CICS system into a CMAS. 

2. Turned a CICS system into a WUI server. 

3. Created a CICSplex. 

4. Defined your CICS systems to the CICSplex. 

5. Modified your existing CICS systems to allow them to connect to the 
CICSplex. 

You can now view information about your systems through the CICSPlex SM 
Web User Interface. 
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To test the Web browser functionality, use a URL of 
http://@ hostname@ : @ portnumber@ , where: 

► @hostname@ is the value that you specified on the TCPIPHOSTNAME 
option of the EYUWUI DD 

► @portnumber@ is the value of @portnumber@ that you specified on the 
TCPIPPORT option of the EYUWUI DD 


2.5 Updating an existing CICSPlex SM setup for CICS 
Explorer 


If you are already a CICSPlex SM user, to enable the CICS Management Client 
interface in your CICSPlex SM Web User Interface (WUI) server, update your 
WUI system parameters to include the new CMCIPORT parameter. The value 
specified is a TCP/IP port number to use for the CMCI. Each WUI server that is 
to provide CMCI support needs a unique (per TCP/IP Stack) port number for the 
CMCIPORT 

Example 2-10 shows a WUI System Parameter file that needs updating. 

Example 2- 1 0 Update the WUI system parameters (before update) 

//EYUWUI DD * 

TCPI PHOSTNAME (MYHOST . EXAMPLE . COM) 

TCPIPPORT (60666) 

DEFAULTCONTEXT (MYPLEX) 

DEFAULTSCOPE(MYSCOPE) 

DEFAULTCMASCTXT (MYCMAS) 

AUT0IMP0RTDSN(CTS41 .CPSM.SEYUVIEW) 

AUTOIMPORTMEM ( EYUEA*) 

// 


Example shows an updated parameter file. 
Example 2-11 Updated WUI system parameters 
//EYUWUI DD * 

TCPI PHOSTNAME (MYHOST . EXAMPLE . COM) 
TCPIPPORT (60666) 

CMCIP0RT(50666) 

DEFAULTCONTEXT (MYPLEX) 
DEFAULTSCOPE(MYSCOPE) 

DEFAULTCMASCTXT (MYCMAS) 
AUT0IMP0RTDSN(CTS41. CPSM.SEYUVIEW) 
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AUTOIMPORTMEM ( EYUEA*) 

// 


To use CICS Explorer, set up a new CICS Management Interface connection. 
The host name must be the value of @hostname@ that you specified on the 
TCPIPHOSTNAME option of the WUI system parameters. The port number to 
use is the value of @cmciportnumber@ that you specified on the CMCIPORT 
option of the WUI system parameters. See Figure 2-9. 

Before a Connection can be created, at least one Credential must exist. 

Figure 2-4 on page 25 shows the Credentials Preferences window where you 
define the UserlD and Password pair that will be used by the Connections 
profiles you create. 
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3 


Implementing IBM CICS 
Explorer 


In this chapter, we discuss how to install the CICS Explorer. We focus on local 
and remote installation and CICS Explorer Security. 


© Copyright IBM Corp. 2010. All rights reserved. 
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3.1 Installing CICS Explorer 


CICS Explorer offers a range of installation options. In this section, we discuss 
the various options. When deciding on the best approach for installing the CICS 
Explorer within an organization it is important to consider your corporate 
guidelines and security requirements for client applications. 

CICS Explorer can either be installed on each users local client machine or on a 
remote server for all users to access. Regardless of which option you choose, a 
users own customized data can be saved to the user private storage area. 

Both local and remote installations of CICS Explorer start with the download of 
the appropriate distribution for your operating system. CICS Explorer is provided 
as an archive file: 

► Windows file is a compressed file 

► Linux is a tar file 

To download CICS Explorer, visit the following web location, and then click the 
appropriate link under Downloads. 
http://www.ibm.com/software/htp/cics/explorer/ 


3.1.1 Installing CICS Explorer locally 

We are going to show you two styles of installing CICS Explorer 

► Simple Install 

► Private Workspace Install 

The Simple install gets you up and running with minimal set up. Th e Private 
Workspace install takes a little more set up but gives you more flexibility. Review 
each style, and use the one that meets your needs. Both install styles can be 
used for the Local and Remote installs. 

Simple install 

The idea behind the Simple install is just that, simplicity. Basically all you do is 
download the install package, and extract the distribution file as appropriate for 
the operating system. Because there is no set up application required to install 
CICS Explorer, it is recommended that you expand the archive file to a suitable 
location on the system’s file system, for example c:\program files\ on Windows 
and /opt/ on linux. 

Figure 3-1 on page 47 shows the structure for Windows. 
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Figure 3-1 Windows view 


Figure 3-2 on page 48 shows the structure for Linux. 
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You can create a desktop shortcut for the CICS Explorer executable file; however, 
essentially at this point basic installation is complete. 

Along with the distribution code at run time, CICS Explorer creates a separate 
directory, known as the workspace, where user specific settings and 
customizations are written. By default this workspace is in your home directory: 

► On Windows, the location is usually c:\Documents and Settings\«User 
Name»\.cicsexplorer\ 

► On Linux, the location is /home/«User Name»/.cicsexplorer 


Note: On some operating systems, folders that begin with a dot are not 
shown by default. 


Figure 3-3 on page 49 through Figure 3-7 on page 51 illustrate the process. 
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1 . From the download site, select and download the appropriate package to your 
workstation: 

http://www.ibm.com/software/htp/cics/explorer/ 



Figure 3-3 Download the CICS Explorer package 

2. Choose a Folder or Directory to unpackage the CICS Explorer binaries into, 
and extract the files, as shown in Figure 3-4. 



Figure 3-4 Expand the Zip file 


3. Create a Shortcut icon that references the cicsexplorer.exe file, as shown in 
Figure 3-5 on page 50. 
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Create a shortcut icon 



CICS Ex 



Figure 3-5 Create a shortcut icon 

4. Start the CICS Explorer, set up a connection, and start Exploring your 


Figure 3-6 shows how a workspace named .cicsexplorer is created and is used 
from now on to store information about your CICS Explorer session. 


Figure 3-6 Start exploring 

All changes, connections, and customization results in data being stored in the 
.cicsexplorer workspace; therefore, back up for recovery purposes. 

Figure 3-7 on page 51 shows you that all instances of the CICS Explorer attempt 
to use this same workspace. 


systems. 


Double click and start exploring 
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Figure 3-7 Using a shared workspace 


If you upgrade the CICS Explorer, the upgraded binaries start to use the shared 
workspace, thus you might experience problems if you attempt to run the older 
version due to changes made to your workspace. 

Additionally, if you try to start a second instance of the CICS Explorer, it will also 
try and use the same workspace but will encounter a sharing failure message, as 
shown in Figure 3-8. 



Figure 3-8 Workspace Sharing Lockout Exception 


The Simple install method is designed to get you up and running quickly, but if 
you require more flexibility, such as the ability to run multiple CICS Explorers at 
the same time or want to run more than one version at a time, you might want to 
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explore using the Private Workspace install option that we describe in the next 
section. 

Installing the private workspace 

This private workspace install option is also simple. It just includes an extra step 
to set up a parameter to create and uses a private workspace that allows you to 
run multiple instances and versions of the CICS Explorer: 

Figure 3-9 through Figure 3-16 on page 57 walk you through the set up process 
to create and use a Private Workspace: 

1 . Select and download the appropriate package to your workstation from the 
following download site: 

http://www.ibm.com/software/htp/cics/explorer/ 



Figure 3-9 Download the CICS Explorer package 

2. Choose a Folder or Directory to unpackage the CICS Explorer binaries into, 
and extract the files, as shown in Figure 3-10 on page 53. 
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Figure 3-10 Expand the Zip file 


3. Create a shortcut icon that references the cicsexplorer.exe file, as shown in 
Figure 3-1 1 . 


Create a shortcut icon 



Figure 3-11 Create a shortcut icon 

4. Display the Properties for the shortcut icon that you just created. Figure 3-12 
on page 54 shows you the format of the -data parameter that is used to point 
the CICS Explorer to a private copy of the workspace. 
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5. In the Target field, add the -data parameter followed by the location and 
custom name of your workspace, which are enclosed in parenthesis. In 
Figure 3-12, we use the version name in the binaries folder and the same 
version name in the workspace file name, so that the two can be recognized 
as a pair. 



Figure 3- 1 3 Start exploring 


54 


IBM CICS Explorer 


When you start your explorer, it uses the directory and name that are provided 
in the -data parameter to create your private workspace. 

Tip: At this point the .cicsexplorer workspace used by the Simple install 
method can exist at the same time; therefore, you can use both install 
methods simultaneously, and any additional CICS Explorer that is started 
without the -data parameter will attempt to use the shared .cicsexplorer 
workspace. 

With each additional install or shortcut icon that you create, use a different 
version of the workspace through the -data parameter, which allows 
multiple versions and running instances. 

Figure 3-14 shows our running CICS Explorer pointing to its own private 
workspace. 


Figure 3-14 Using a private non-shared workspace 

If you copy a shortcut icon or create a new one, you must modify the Target 
information to always point to a new private workspace; otherwise, you will 
end up with the same issues as the Simple install where you share the 
workspace. 

Figure 3-15 on page 56 shows a new shortcut icon being created using a 
different binaries folder and workspace. Comparing the shortcut icon in 
Figure 3-12 on page 54 and the one in Figure 3-15 on page 56 you can see 


Using a private non-shared workspace 




Non-Shared Private Workspace 
Unique for this CICS Explorer Binaries folder 
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that if we start both CICS Explorers up simultaneously, they use different 
Binaries and workspaces. 



Figure 3-15 Setup of the -data parameter 


6. Finally Figure 3-16 on page 57 shows how two different versions can be 
managed and run simultaneously. We recommend that you backup the 
binaries and workspaces as a pair because if one is, lost, damaged, or 
corrupted, you can easily recover it. 
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If you recover a Binary/Workspace pair, you must create a new shortcut icon 
using an appropriately configured -data parm to link the two together. 


3.1.2 Installing CICS Explorer remotely 

You can also install CICS Explorer on a remote server for clients to access. The 
benefits of this remote server include only having one single copy of the binary to 
update; however, execution might be a little slower than running the client locally. 

The simplest way to install CICS Explorer remotely is to install CICS Explorer 
onto a shared drive. Each client machine can then access the shared drive. 
Individual users can then start the CICS Explorer by directly running the 
executable file or by creating a local shortcut for the remote executable on the 
local machine. When CICS Explorer is run this way, the user’s workspace is 
written to their local machine, unless explicitly specified. (See 3.1 .1 , “Installing 
CICS Explorer locally” on page 46). When CICS Explorer is run from a remote 
drive there might be a delay in the time that it takes for CICS Explorer to start 
because the binary data is copied over the network. 

The benefits of running CICS Explorer remotely are that maintenance needs only 
to be applied to a single copy of the application binary, and it also removes the 
overhead of rolling the application out to every workstation. The disadvantage of 
running CICS Explorer remotely is that the initial start time of CICS Explorer can 
be longer than if it were running locally. 
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You can run CICS Explorer remotely regardless of which operating system is 
used because the remote server is just acting as a file store. All of the processing 
is performed on the local machine. 

You can also run CICS Explorer from a shared Linux server using any windows 
system to allow the GUI to be displayed on a user’s local terminal by installing the 
CICS Explorer onto a Linux server in a location that is readable by logged on 
users. Users can log onto the remote system using their preferred Windows 
package. After the users log on, they can run CICS Explorer on the remote 
system. When CICS Explorer is being run from a remote Linux server in this 
manner, the CICS Explorer binary executes on the server using the server’s 
memory and CPU resources. The user’s workspace is stored in the user’s home 
directory and not on the local workstation. 


3.2 CICS Explorer security 

There are several areas to consider in regards to the CICS Explorer and Security 
depending on which type of connection you are using. Regardless of your 
connection type, Link Security and Credential Authorization are also available. 

In this section, we address the following four areas: 

► Link Security 

► Credential Authorization 

► Security for a stand-alone CICS Region connection 

► Security for a CICSPlex SM connection 

3.2.1 Link Security 

When CICS Explorer connects to any CICS system it can encrypt the link 
between it and the remote system. By default CICS Explorer uses unsecured 
HTTP requests, which means that system information flows over the network as 
plain text. 

Secure Sockets Layer (SSL) encryption can be used to encrypt the data flow 
between CICS Explorer and CICS, which are both supported by changing the 
TCP/IP Service that is used by the CICS Explorer to connect to the CICS system. 

See 3.2.5, “Using SSL” on page 59 for Link Security setup. 
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3.2.2 Credential authorization 


When connecting to a CICS System through CICS Explorer users must use the 
same credentials they use to log directly into either the CICS region for a 
stand-alone CICS Region (SMSS) connection or into the CICSPlex SM Web User 
Interface for a CICSPlex SM connection. When the user makes a request against 
the system, CICS or the CMAS verifies that the credentials are correct and that 
the user has the correct authority to make that request. 

See 3.2.6, “Using HTTP Basic Authentication” on page 60 for Authentication 
Security setup. 

3.2.3 Security for a stand-alone CICS Region (SMSS) connection 

When connecting to a single CICS region through a stand-alone CICS region 
(SMSS) connection, CICS Explorer uses existing CICS Command and 
Resources security profiles to allow or reject requests; therefore, the same level 
of security that is available within your existing CICS environment is available 
through the CICS explorer. 


3.2.4 Security for a CICSPlex SM connection 

When connecting to a CICSPlex through a CICSPlex SM connection, CICS 
Explorer uses CICSPlex System Manager to process or reject requests using 
CICSPlex SM security. The same level of security that is available in your existing 
CICSPlex SM environment is available through the CICS explorer. 

Tip: CICSPlex SM security uses the CPSMOBJ profiles on top of existing 
Command and Resource level profiles to secure a CICSPlex SM environment; 
whereas, only Command and Resource level profiles are used to secure 
stand-alone CICS region (SMSS) connections. 


3.2.5 Using SSL 

CICS Explorer can use SSL to encrypt the link between it and the CICS system. 
However CICS Explorer cannot use a private certificate to affirm a user ID. The 
process is slightly different depending on if you are connecting CICS Explorer to 
a WUI server or a single CICS region. 
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SSL connection to a WUI server 

Add the following WUIPARMS: 

► TCPIPSSL(YES) 

► TCPIPSSLCERT(NAME) 

The name of the TCPIPSSLCERT must be the name of a certificate that is 
attached to the keyring that is specified in the keyring SIT parameter. If 
TCPIPSSLCERT is omitted, the default certificate that is attached to the keyring 
is used instead. 

Setting this parameters ensures that when CICS defines the TCP/IP Service 
resource definition for the CMCI port that the correct attributes are set for SSL 
operation. 

SSL connection to a single CICS region 

Change the TCPIPService resource that you are using to connect to the CICS 
region: 

SSL = YES 

You also must ensure that you have a default certificate specified in the keyring 
that CICS is using. 


3.2.6 Using HTTP Basic Authentication 

When using HTTP Basic Authentication, when you attempt to make a connection 
to the TCP/IP port, you are prompted to provide a username and password 
before the connection is established. HTTP basic authentication can be used to 
provide a level of DOS attack protection because only users with valid credentials 
are allowed to make a connection. 

To use HTTP basic authentication in your environment, you must specify the 
value basic for the Authenticate property of the TCP/IP Service that is used as 
the entry point for the CICS Explorer. 

During a connection attempt, CICS Explorer uses the same credentials that you 
specified in the connection preferences in response to a HTTP Basic 
Authentication Challenge. 

Tip: If the system you are connecting to does not require you to sign on, you 
must enter a username into the connection preferences panel, but you can 
leave the password field blank. 
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3.2.7 CICSPlex Security Scenario 

Full details regarding CICSPlex security definitions are in the CICSPlex SM 
security section, in the CICSPlex manual. 

RACF® security profiles can be created based on function.type.context.scope: 

► Function: CICSPlex function impacted by the RACF Profile, for example, 
ANALYSIS - Real Time Analysis, OPERATE - Operations, and so on. 

► Type: Valid subgroup of the function, for example, for function OPERATE, a 
valid type is PROGRAM. 

► Context: Either the fully qualified or generic name of a CMAS or CICSplex: 

• In the case of CONFIG or TOPOLOGY, the context must be a CMAS. 

• For all other definitions, the context must be a CICSplex. 

► Scope: Either the fully qualified or generic name of a CICS system: 

• In this context, scope cannot be used to specify a CICSPlex Topology 
group or CICSPlex BAS logical scope. 

• You cannot specify scope when context is a CMAS or type is DEF 
unless you are defining security rules for CSD resources. 

Details regarding the use of READ, ALTER, and UPDATE: 

► READ allows users to VIEW resources. 

► In the case of the OPERATE and BAS functions: 

- UPDATE allows NEWCOPY, SET, OPE, CLO, and MODIFY (including 
Shutdown on OPERATE. REGION). 

- ALTER allows INSTALL, DISCARD, CREATE, and DELETE. 

► For all functions other than OPERATE and BAS: 

- UPDATE allows INSTALL, DISCARD, CREATE, DELETE, and MODIFY. 

- ALTER only applies to OPERATE and BAS definitions. 

Details regarding the CICSPlex Security Scenario. The company Redbooks is 
creating CICSPlex RACF security profiles, which must achieve the following 
objectives: 

► Give all users READ access to all resources. 

► Limit administration of the following CICSPlex functions to the Company CICS 
team members: 

- ANALYSIS 

- BAS 

- CONFIG 
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- CSD 

- MONITOR 

- TOPOLOGY 

- WORKLOAD 

► Allow the same resource access, within the CICSPlex OPERATE function 
rules, as currently defined within their RACF command-level security rules. 
This access currently differs between their Test and Production environments. 

► Set up a rule to allow READ only access for any other CICSPlex functions 
and types that were not secured. This rule is intended as a fail-safe for 
anything not covered in their new security profiles. 

► Create rules that can be shared across all their Test and Production 
environments. Currently all of their Production CICSplex environments begin 
with PLXP, and all of their Test environments use PLXT. 

In Figure 3-17 on page 63, we can see that the following techniques were used 
to achieve all of the Company Redbooks objectives: 

► User * was given READ access in all cases. 

► The ANALYSIS, BAS, CONFIG, CSD, MONITOR, TOPOLOGY, and 
WORKLOAD functions were left generic with regard to type.context.scope, 
allowing those security rules (restricting administration access to the CICS 
team) to be used across all environments: 

- The OPERATE function was broken down by type. 

- In cases where the rules for the OPERATE function type are the same for 
all environments, no context is used. 

- In cases where the rules for the Test and Production environments differ, a 
generic context (representing the Production PLXP* and Test PLXT* 
environments) was used. 

- Company RedBooks associated the RACF user groups, appropriate to the 
function.type.context, based on their current RACF command level 
security rules. 

► The ** rule allows READ-only access for anything that is not covered, which 
provides a fail-safe. 

Figure 3-17 on page 63 shows Company Redbooks CICSPlex security matrix. 
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RACF Groups Associated with the CPSMOBJ CLASSES 1 

SR CLASS(CPSMOBJ) 

Environment 

Any User 
(USER*) 

CICS Team 
(CICSGRP) 

Operations 

(OPERGRP) 

(DEVGRP) 

ANALYSIS.** 

ALL 

Read 

Update 



BAS.** 

ALL 

Read 

After 



CONFIG.** 

ALL 

Read 

Update 



CSD.** 

ALL 

Read 

After 



OPERATE.AI MODEL.** 

ALL 

Read 

After 

Update 


OPERATE. BRFACIL.** 

ALL 

Read 

After 

Update 


OPERATE. CONNECT. PLXT*.** 

Test 

Read 

After 

Update 

Update 

OPERATE.CONNECT.PLXP*.** 

Prod 

Read 

After 

Update 


OPERATE. DB2D BCTL.** 

ALL 

Read 

After 

Update 


OPERATE. DOCTEMP. PLXT*.** 

Test 

Read 

After 

Update 

Update 

OPERATE. DOCTEMP.PLXP*.** 

Prod 

Read 

After 

Update 


OPERATE. ENQMODEL.** 

ALL 

Read 

After 

Update 


OPERATE. ENTJAVA.** 

ALL 

Read 

After 

Update 


OPERATE. EXIT.** 

ALL 

Read 

After 

Update 


OPERATE. FEPI.** 

ALL 

Read 

After 

Update 


OPERATE.FILE.PLXT*.** 

Test 

Read 

After 

Update 

Update 

OPERATE. FI LE.PLXP*.** 

Prod 

Read 

After 

Update 


OPERATE.IPCONN.PLXT*.** 

Test 

Read 

After 

Update 

Update 

OPERATE.IPCONN.PLXP*.** 

Prod 

Read 

After 

Update 


OPERATE. JOURNAL.** 

ALL 

Read 

After 

Update 


OPERATE.PARTNER.** 

ALL 

Read 

After 

Update 


OPERATE. PROCTYPE.** 

ALL 

Read 

After 

Update 


OPERATE.PROFILE.** 

ALL 

Read 

After 

Update 


OPERATE.PROGRAM.PLXT*.** 

Test 

Read 

After 

Update 

Update 

OPERATE.PROGRAM.PLXP*.** 

Prod 

Read 

After 

Update 


OPERATE.REGION.** 

ALL 

Read 

After 

Update 


OPERATE. RQMODEL.** 

ALL 

Read 

After 

Update 


OPERATE.TASK.PLXT*.** 

Test 

Read 

After 

Update 

Update 

OPERATE.TASK.PLXP*.** 

Prod 

Read 

After 

Update 


OPERATE.TCPIPS.PLXP*.** 

Test 

Read 

After 

Update 

Update 

OPERATE.TCPIPS.PLXT*.** 

Prod 

Read 

After 

Update 


OPERATE.TDQUEUE.PLXT*.** 

Test 

Read 

After 

Update 

Update 

OPERATE.TDQUEUE.PLXP*.** 

Prod 

Read 

After 

Update 


OPERATE.TERMINAL.PLXT*.** 

Test 

Read 

After 

Update 

Update 

OPERATE.TERMINAL.PLXP*.** 

Prod 

Read 

After 

Update 


OPERATE.TRAN. PLXT*.** 

Test 

Read 

After 

Update 

Update 

OPERATE.TRAN.PLXP*.** 

Prod 

Read 

After 

Update 


OPERATE.TSQUEUE.PLXT*.** 

Test 

Read 

After 

Update 

Update 

OPERATE.TSQUEUE.PLXP*.** 

Prod 

Read 

After 

Update 


OPERATE.UOW.** 

ALL 

Read 

After 

Update 


TOPOLOGY.** 

ALL 

Read 

Update 



WORKLOAD.** 

ALL 

Read 

Update 




ALL 

Read 

Update 




Figure 3-17 Company Redbooks CICSPlex security matrix 


3.3 Updating the CICS Explorer 

Because CICS Explorer is built on Eclipse technology, you can automatically 
update it using the same mechanism that is used to update Eclipse. 
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3.3.1 Updating from the Internet 


You can update CICS Explorer directly from a Web server. IBM hosts an update 
site that contains updated versions of the CICS Explorer. Alternatively, your 
enterprise might provide an internal site. 


CICS Explorer updates: All CICS Explorer updates are available from: 

http : //downl oad . boul der . i bm. com/i bmdl /pub/software/htp/ci cs/updates/ 
explorer/ 


To update the CICS Explorer from the IBM site: 

1 . From the Help menu, select Software Updates. 

2. From the Installed Software tab, select IBM CICS Explorer, as shown in 
Figure 3-18. 

3. Click Update. 



Figure 3-18 Software Updates window 


CICS Explorer downloads and installs the updates. 
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If your system administrator supplied you with a URL to use as an internal mirror 
of the IBM update site, alter your configuration to remove the IBM update site, 
and add the internal one: 

1 . From the Help menu, select Software Updates. 

2. From the Available Software tab, select Manage Sites. 

3. Select the site that points to: 

http : //downl oad . boul der . i bm.com/ibmdl /pub/software/htp/ci cs/updates/ 
explorer/ 

4. Click Remove. The IBM site is now removed from the list of update sites. Now 
add your internal site, and click Add. 

5. In the next dialog, enter the name of the update site as provided to you by 
your system administrator, and click OK. 

You can now update the CICS Explorer as shown. If the Web server that is 
hosting the update site requires authentication, you are prompted for your 
credentials. 


Restriction: Because of issues surrounding the update mechanism, we do 
not recommend that you allow CICS Explorer to save your password when 
connecting to an update site. 


3.3.2 Updating from an archive file 

If you cannot connect to the Internet to update CICS Explorer, it is possible to 
update from a local archive file. An archive file is a compressed file that contains 
the same content that the update site contains. 

To update CICS Explorer from an archive file: 

1 . Download the archive file to your local machine. Put the file in a location that 
you can remember. 

2. From the Help menu, select Software Updates. 

3. From the Available Software tab, select Manage Sites. 

4. Click Add -» Archive. 

5. On the next dialog, navigate to the archive file that you downloaded. 

6. Click Open -» OK. 

You can now update the CICS Explorer, as we discussed in 3.3.1 , “Updating from 
the Internet” on page 64. 


Chapter 3. Implementing IBM CICS Explorer 65 



3.3.3 Updating automatically 


After you configure CICS Explorer with an update site that the software can 
access, you can configure CICS Explorer to automatically search for updates on 
a regular basis, which ensures that you are kept up-to-date with new features of 
the CICS Explorer: 

1 . From the Help menu, select Software Updates. 

2. Expand Install/Update. 

3. Select Automatic Updates. Figure 3-19 is displayed. 



Figure 3-19 Automatic Update dialog 

4. The dialog in Figure 3-19 gives options that allow you to specify when to 
check the update site for new updates. After you make your selections, click 

Apply -> OK. 
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3.4 Enterprise deployment 


In this section, we discuss enterprise deployment of CICS Explorer. 

3.4.1 Providing local mirrors 

If your enterprise does not allow for users to access the Internet, it is possible to 
set up an internal mirror of CICS Explorer. Users can install and receive updates 
from the local mirror. 

The CICS Explorer installation archive file can be freely downloaded and stored 
on an internal server to allow internal downloads. Alternatively it can be 
incorporated into an automated software delivery system. 


Archive sites: The archive site files are stored separately on the main update 
site: 

http://www.ibm.com/support/fixcentral/ 

CICS Explorer is under the product group WebSphere. 


If you are providing a local mirror for users, you might also want to provide a local 
mirror of the IBM update site so that users can update their copy of CICS 
Explorer. This can either be a local copy of the update archive file or a copy of the 
entire update site. 

The best practice is to provide a mirror of the IBM update site that is regularly 
updated. Using this method users can automatically update CICS Explorer from 
the local mirror with little intervention, ensuring that users are always using the 
most up-to-date version of the software. 

Obtaining an archive site file 

To download an archive site file: 

1 . Go to the IBM Fix Central web site at: 
http://www.ibm.com/support/fixcentral / 

2. Enter the requested information, as shown in Figure 3-20 on page 68. 
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Product Group 



| WebSphere 

~ u 


Product 



| CICS Explorer 


_d 

Installed Version 

1 1.0 0 6 ~^~l 

Platform 

| Windows 32-bit. x86 ▼! 

W Continue 




Figure 3-20 Fix Central site 


Set the Installed Version to your current CICS Explorer release. Set the 
Platform to the one that is appropriate for your installation. 

3. Click Continue. 

4. Identify the fixes that you want to include in the archive site file, as shown in 
Figure 3-21 on page 69. 


IBM CICS Explorer 


Browse for fixes 
r Do not show fixes that 
change my installed version 
(1.0. 0.6) 

Browse for all fixes for your specific 
rwnHnrt. release, and platform. 

r APARorSPR 

Search for fixes by entering an APAR or 
SPR number (e g.. PK10998). 

r Individual fix IDs 

— Search for updates by entering one or 

1 

more fix IDs each separated by a 


comma (e g., ibm fw aacraid 8kl- 


5.2. 0-1541 1_linux_32 -64). 

f- Text 

Search for fixes containing all the 

1 

entered key words, such as problem 


area, exception, or message ID, in any 


order. You can embed one or more 


asterisks (*) into the search string to 


perform a wild card search 

p Recommended 

Display a list of fixes recommended by 


Fix Central for your specific version and 


platform. 


Figure 3-21 Fix Central Fix Identification panel 


5. Click Continue. You are presented with a fix pack containing all of the fixes 
that match your selection criteria, as shown in Figure 3-22 on page 70. 
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Select fixes 

The following results match your request. Select the fixes you wish to download. £> Generate a link to this 
To trv a different auerv. ao to the Identify fixes Daae. pagp 

Refine results: 


| All fixes 

-3 O 

O Select all 

Deselect all O Show fix details 

1-1 of 1 results 


r 1. fix pack: 1.0.0.7-WS-CICSExplorer-WinLin-IZ79765 Jul 16, 2010 

IZ79765 

£■ More Information 

1-1 of 1 results 


O Select all 

O Deselect all (fj) Show fix details 

O Continue 

O Back 


Figure 3-22 Fix Central Fix pack panel 


You can get more information, regarding the fix pack by following the link 
provided. You can also choose to select the fix pack provided, or use the 
Refine results drop-down to further refine your search criteria. 

6. Select the desired fix pack and click Continue. You are asked to specify your 
download options, as shown in Figure 3-23 on page 71. 
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Select download options 

Select the download method to be used to download fixes. 

<*■ Download using Download Director ® What is this? 

C Download using your browser (HTTP) 

CAUTION: Do not assume that Fix Central will show you all the 
prerequisites you need. 

Be sure to always click the More information link for additional prerequisite and 
other important fix information. Click here for an explanation of what 
prerequisites you can expect Fix Central to provide. 

17 Include prerequisites and co-requisite fixes (you can de-select the ones you 
do not need later) 

& Continue O Back 


Figure 3-23 Fix Central Download Options panel 

7. After selecting your download options, click Continue. You are provided with 
the link to download the fix pack. 

You can now update the CICS Explorer, as shown in 3.3.1 , “Updating from the 
Internet” on page 64. 

3.4.2 Pre-installation customization 

When considering implementing CICS Explorer within an enterprise you might 
want to provide some customizations that are specific to your organization, for 
example, pre-configured connection information to your CICS systems and 
custom panel layouts for specific user groups. 

CICS Explorer saves customization and preferences within a folder known as the 
workspace. If you want to provide pre-installation customizations to the CICS 
Explorer, you must also provide a copy of the workspace that contains the 
customizations and ensure that your users start CICS Explorer correctly to use 
this workspace: 

1 . Install CICS Explorer using -data «folder name» to specify a new 
workspace. 


Workspace Location: Record the location of the workspace folder 
because you will need it later. 
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2. Make your customizations. 

3. Export the created workspace to an archive. 

Customizing perspectives 

You can customize the CICS Explorer to create new perspectives. Custom 
perspectives can be useful to complete certain tasks, for example, when 
investigating why a certain resource is failing, it is useful to only see the views 
that are associated with that resource. Working with CICS Web services might 
only require the web service, pipeline, urimap, and TCP/IP operational views. 
Creating new application definitions require the definitional views. 


Restriction: You cannot add internal update site locations to a customized 
workspace. 


To create a new perspective, change and arrange the number of views on display 
by: 

► Opening new views 

► Closing open views 

► Changing the position and size of a view 

► Changing the columns that are displayed as part of a view 

After the window is arranged as required: 

1 . On the menu bar, click Window. 

2. Click Save Perspective As. 

3. Enter a useful name for the new perspective, and click OK. 

The perspective is now saved and available from the Window, Open Perspective 
dialog. 

Customizing connection details 

You can pre-customize CICS Explorer to have predefined connection definitions 
to the CICS systems that your users want to connect to: 

1 . On the menu bar, click Window. 

2. Select Preferences ->• Connections. 

3. Enter the connection details. 

Tip: When entering connection details do not enter your own user ID and 
password; however, you must enter some text in the userlD field to ensure 
that CICS Explorer saves the connection. We suggest that you enter USER. 

4. Click Apply, and then click OK. 
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After you finish customizing the CICS Explorer, you must close it before you can 
successfully export the workspace. 

Now you can compress the workspace into an archive file to share with your 
users. 


Important: Ensure the integrity of the archive after you create it. Some 
compression programs omit folders and files that begin with the character. 
Such files exist in the workspace. 


To consume the customizations, extract the workspace to your local machine. 
When starting the CICS Explorer, specify where to extract the workspace to. 


3.5 Using plug-ins 

The individual plug-ins are downloaded from the appropriate support sites in the 
form of a site compressed file that contains the executable code and the 
necessary licence agreements. After the file is downloaded onto your machine, it 
can be integrated into the installation: 

1 . From the Help menu, select Software Updates, as shown in Figure 3-24. 



Figure 3-24 Software Updates menu 

2. Click the Available Software tab, and click Manage Sites, as shown in 
Figure 3-25 on page 74. 
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Figure 3-25 Available Software tab 

3. Click Add. In the Add Site pop-up, shown in Figure 3-26 on page 75, click 
Archive to select the compressed file that you downloaded. 
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Figure 3-26 Add Site window 


4. Click OK to close the pop-up. 

5. Click OK to close the Available Software Sites window. 

6. In the Available Software tab, select the plug-in that you want to install, as 
shown in Figure 3-27 on page 76. 
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Figure 3-27 Plug-in check box 

7. Click Install. Eclipse ensures that your selection is compatible with your 
installation. If everything is fine, Eclipse prompts you to accept the terms of 
the license agreement. 

8. Agree to the terms of the license, and then click Finish. 

9. After the installation is finished, you are prompted to restart CICS Explorer. 
Click Yes. After the installation is complete, the Welcome window is displayed 
to show the new functionality that was added to CICS Explorer. 
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4 


CICS Explorer base 
familiarization 


In this chapter, we look at the CICS Explorer base and discuss perspectives, 
connections, views, and the editor. 


© Copyright IBM Corp. 2010. All rights reserved. 


77 




4.1 Perspectives 


CICS Explorer provides two perspectives for interacting with CICS: 

► Resource 

The Resource perspective is primarily concerned with the manipulation of 
event bindings and bundle projects. 

► CICS SM 

The CICS SM perspective is concerned with the viewing and manipulation of 
CICS resources and is the focus of this chapter. 


4.2 Connections and credentials 

In this section, we discuss setting up connections and credentials. 


4.2.1 Connection Manager 

In the Explorer, the status of any connections are represented by the Connection 
Manager, which resides in the bottom right corner of the Explorer window, as 
shown in Figure 4-1 on page 79. 
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Figure 4- 1 Connection Manager location 


When the CICS Explorer is configured with some connections, clicking the arrow 
on the connection status trim widget displays a list of available connections. 
Selecting one of these causes the CICS Explorer to attempt to establish that 
connection using the saved details. The connection manager icon represents the 
state of the named connection. Table 4-1 shows the Connection Manager status 
icons. 


Table 4- 1 Connection Manager status icons 


Connection Status icon 

Connection state 

a 

Disconnected 


Connecting 
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Connection Status icon 


Connection state 


© 

¥ 

% 


Connection Established 


Secure Connection Established 
Connection Error 


When you click the red square, the system attempts to connect to the currently 
named connection. While connecting, the icon changes to a yellow diamond. A 
successfully established connection is represented by a green circle. When a 
connection is established, clicking the green circle causes the Explorer to 
disconnect. 


4.2.2 Connections and Credentials Preference pages 

Connections and Credentials provide the CICS Explorer details about the CICS 
system you are connecting to, such as its location and authentication 
requirements. The credentials provide the CICS Explorer the required UserlD 
and Password information to complete the connection. In the CICS Explorer 
connection, information is managed through the Connections Preference page. 

Before you can create a connection you must first define at least one credential. 

To access the Connections Preference page: 

1 . Click the text on the connection status trim widget or use the menus 
Window ->• Preferences, to open the preferences dialog. 

2. From the tree on the left side, select Credentials, as shown in Figure 4-2 on 
page 81 . 
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Figure 4-2 Credentials Preferences page 

3. Click New, and enter a UserlD and optionally a password, and give it a 
meaningful name that you will use to reference this Userid / Password pair. 

4. Click Apply to store your credentials. You might need several credentials 
based on how many different systems you need to access. 

The Name and User ID fields are mandatory. Passwords can optionally be 
specified. If a password is not specified, CICS Explorer prompts for one when 
establishing a connection. 

After you have your credentials defined, you can continue creating your 
connections definitions. 

5. From the tree on the left side, select Connections, as shown in Figure 4-3 on 
page 82. 
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Figure 4-3 Connections Preferences page 

To enter details for a new connection: 

1 . Select the type of connection that you want to define, and click New. 

2. Give your connection a meaningful name, which is displayed in the 
Connection Manager widget on the bottom right of the CICS Explorer. 

3. Fill in the URL to your Host LPAR and the port number that either your WUI 
region is listening on or your single region is listening with. 

4. Expand the Credentials box, and select the appropriate ID credentials. 

5. After you specify your connection details, click Apply to save them. 
Alternately, you can click OK to save and close the preferences dialog. 

Connections are categorized in the preferences page based on connection type. 
To view available connections for a specific connection type, in the Type combo, 
select the type of connection you want to examine. The Name combo is then 
populated with a list of connections of that type from which you can select. 

The Type, Name, Host name, Port number, and Credential are mandatory. 
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4.2.3 CICS Explorer connectivity 


In our CICS Explorer, we click Window Preferences, and select the 
connection settings field, as shown in Figure 4-4. 



Open perspective 
Show View 


Save Perspective As... 
Reset Perspective... 
Navigation 



Figure 4-4 Explorer preferences 


We use connection type CICS management client interface (CMCI), as shown 
in Figure 4-5. 



Figure 4-5 CICS Explorer connection options 
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Connection type: We use connection type CICS Management Interface to 
enable update capability. The default connection type, CICSPlex SM Data 
Interface, allows read-only capability. 


Our Web user interface (WUI) server (Hostname: wtsc66.itso.ibm.com) has port 
= 16001 . The CMCIPORT system initialization parameter for our WUI is set as 
CMCIPORT =16001. 

In the CICS Transaction Server for z/OS Version 4 Information Center, read 
Setting up the CICS management client interface for further details: 
https : //publ i b . boul der . i bm. com/i nfocenter/ci csts/v4rl/i ndex . j sp?topi c=/ 
com. i bm. ci cs . ts . cl i entapi . doc/topi cs/cl i entapi_setup . html 


4.3 Views 

In this section, we look at the two types of views: tabular and tree. 

The context limits what data is displayed in most views: 

► The context of a view can be manipulated by the CICSplex Explorer view or 
the CICSplex Repositories view. 

► The CICSplex Explorer view can be used to set the context to a CICSplex or 
CICS region. 

► The CICSplex Repositories view can be used to set the context to a resource 
group or system group. 

► The Resource Group Definitions view can also be used to set the context to a 
resource group. 

CICS Object Table Views use the last appropriate context that the user selected 
when populating, for example, only CICS definition views repopulate using a 
resource group because of their context when one is selected by the user. 

4.3.1 The CICSplex Explorer view 

When connected to CICSPlex SM, the CICSplex Explorer view, which is shown in 
Figure 4-6 on page 85, displays a list of CICSplexes. When using CMCI to 
connect to a single CICS region, the CICSplex Explorer view shows the region to 
which you are connected. 
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Figure 4-6 The CICSplex Explorer view 


Expanding a CICSplex shows the managed regions within that CICSplex. If the 
icon is colored, then the managed region is active. If the icon is monochrome, the 
region is inactive. 

Selecting a CICSplex or a managed region sets the context accordingly. 


4.3.2 The CICSplex Repositories view 

The CICSplex Repositories view, shown in Figure 4-7 on page 86, shows the 
available resource groups, the available system groups, and their members. 
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Table 4-2 shows the icons for the CICSplex Repositories view. 
Table 4-2 CICSplex Repositories view icons 


Icon 

CICS object 


System Definition 


System Group 

m 

Resource Group 


Selecting any of these resources in the CICSplex Repositories view sets the 
context of any open CICS Object Table view where appropriate. System groups 
can be expanded to view their members, which might be either nested system 
groups or system definitions. 

4.3.3 CICS Object Table views 

CICS Object Table views display CICS resources of a specific type from the 
current context. You cannot open Resources views from the Administration, 
Operations, WLM, and RTA menus. 
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Operations views 

The Operations views are: 

► Atom Services 

► Bundles 

► Bundle Parts 

► Capture Specifications 

► CMAS to CMAS Links 

► Completed Tasks 

► CorbaServers 

► DBCTL Subsystems 

► DB2 Connections 

► DB2 Entries 

► DB2 Transactions 

► Document Templates 

► Event Bindings 

► Event Processing 

► Files 

► Global Dynamic Storage Areas 

► Interval Control Requests 

► IPIC Connections 

► ISC/MRO Connections 

► JVM Class Caches 

► JVM Pools 

► JVM Profiles 

► JVM Servers 

► JVM Status 

► Libraries 

► Library DS Name 

► Pipelines 

► Process Types 

► Programs 

► Regions 

► RPL List 

► Tasks 

► Task Associations 

► TCP/IP Services 

► TD Queues 

► Terminals 

► Transactions 

► Transaction Classes 

► TS Models 

► TS Queues 

► Unit Of Work Enqueues 

► URI Maps 
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► Web Services 

► WebSphere MQ Connections 

► WebSphere MQ Connection Statistics 

► WebSphere MQ Initiation Queues 

► XML Transforms 

► CICSplexes 

► CMAS Details 

Administration views 

The Administration views are: 

► Atom Service Definitions 

► Bundle Definitions 

► CICSPlex Definitions 

► CMAS to CMAS Link Definitions 

► CorbaServer Definitions 

► DB2 Connection Definitions 

► DB2 Entry Definitions 

► DB2 Transaction Definitions 

► Deployed JAR File Definitions 

► Document Template Definitions 

► Enqueue Model Definitions 

► File Definitions 

► IPIC Connection Definitions 

► ISC/MRO Connection Definitions 

► Journal Model Definitions 

► JVM Server Definitions 

► Library Definitions 

► LSR Pool Definitions 

► Map Set Definitions 

► Partition Set Definitions 

► Partner Definitions 

► Pipeline Definitions 

► Process Type Definitions 

► Profile Definitions 

► Program Definitions 

► Request Model Definitions 

► Session Definitions 

► System Definitions 

► System Group Definitions 

► TCP/IP Service Definitions 

► TD Queue Definitions 

► Terminal Definitions 

► Transaction Definitions 

► Transaction Class Definitions 
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► TS Model Definitions 

► Typeterm Definitions 

► URI Mapping Definitions 

► Web Service Definitions 

► WebSphere MQ Connection Definitions 

► Group List Definitions 

► Resource Group Definitions 

RTA views 

The RTA view is: 

► Events 

WLM views 

The WLM view is: 

► Active Workloads 


4.4 The Resources view 

Figure 4-8 illustrates the anatomy of a Resources view. 



Figure 4-8 Anatomy of a Resources view 


The Resources views are tabular views, where each row corresponds to a CICS 
resource in the current context. Each column represents a different attribute on 
the CICS resource type. At the top of each resource view is a status bar that is 
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specific to that view, showing the context that is being used to populate the view, 
the CICS name for the resource that the view is displaying, the number of 
records that were available the last time the content was refreshed, and the time 
that the view content was last refreshed. To manually refresh the content of a 
Resources view, click Refresh, and the view automatically refreshes, if visible 
when the context changes. 

To minimize network traffic and server load, CICS Explorer only retrieves enough 
resources to fill the visible portion of the table. The remainder of the resources 
are retrieved as the table is scrolled. A consequence of this is that if you are 
viewing a resource for which a large number of records exist, you might have to 
wait for the table to be populated as you scroll. 

CICS Explorer uses two special values to represent some attribute state, N/A and 

► If an attribute is not supported on an older release of CICS in a CICSplex, the 
explorer populates its cell in the column with N/A. 

► If CICS Explorer encounters an unexpected value for an attribute, its cell in 
the column is populated with ?. 


Values that represent attribute state: Both of these values are legitimate 
string values for attributes, so you must carefully determine their meaning. 


Columns 

Each column in a CICS resource view represents a specific attribute on the type 
of resource that is being viewed. You can manipulate columns in a resource view, 
as shown in Figure 4-9 on page 91 , by dragging them to a different position to 
change the order or by dragging the column separators to change the width. Any 
changes that you make to the layout of the table are persisted by CICS Explorer. 

Each resource view has a predefined set of default columns to display, which you 
can customize by going to the view menu and selecting Customize Columns. 
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Figure 4-9 The Customize Columns dialog 

In the Customize Columns window, you can: 

► Move attributes between the left list of available attributes and the right list of 
displayed attributes by selecting them from a list and clicking Add or Remove 
as appropriate. 

► Click Close to apply your changes. 

► Click Reset to revert the displayed columns to the predefined defaults. 

► Reset the columns to the default state by selecting Reset Columns from the 
view menu. 


Note: If you set the columns for a view without connecting, establish a 
connection and further customize the columns. Selecting reset columns resets 
them to the state that you established without a connection. 


Filtering 

CICS Object Table Views can be filtered upon the value of most attributes. The 
filter area, Figure 4-1 0 on page 92, displays the currently selected filter fields and 
the values being used as filter criteria. Each CICS Resource view has a default 
filter field that is initially presented. You can select additional filter fields by 
checking the appropriate box from the Choose filter attributes submenu in the 
view menu. The submenu displays a list of check boxes that represent all 
currently visible columns in the view. To filter on additional attributes, you must 
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first add them to the table using the customize columns dialog. Remove filter 
fields by clearing them from this list. 


Attribute filtering: You cannot filter on date attributes. You cannot filter on 
Region Name or CICS Release. 


1 2 3 4 



1. Filter Field Name 

2. Filter Field Control 

3. Apply Filter Button 

4. Clear Filter Button 

Figure 4-10 Filter area anatomy 

For each filter field that is added to the view, the filter area will display the 
attribute name and an appropriate control for entering a value upon which to 
restrict the content of the view, either a text box or a combo field. 

To apply a text filter: 

1 . Enter the characters on which you want to filter into the text box. 

2. Either press Enter or click Apply Filter. 

3. Append an * character to the end of your filter string as a wildcard, matching 
any subsequent combination of characters. 

To apply a combo filter: 

1 . Select one of the available options from the list, and click Apply Filter. 

2. Select the blank entry to make CICS Explorer disregard that filter. 

3. Click Clear Filter to set the value of all of the displayed filters to blank, but 
they are not removed from the view. The state of the filter area is saved by 
CICS Explorer and recreated when the view is opened. 

CICS Object Table views with multiple types 

In some cases, a CICS Resource view can reflect results for multiple CICS 
Resources, for example, the TD Queues view can display either Indirect, 
Extrapartition, Intrapartition, or Remote TD Queues. 

Figure 4-1 1 on page 93 shows the location of the toolbar from which the 
resource type for a view can be switched. Hover the cursor over each button to 
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determine the type of resource that is represented. The type of resource last 
used to populate the view is displayed in the view status bar. 



Figure 4-11 Resource selection toolbar location 


Table 4-3 shows the views that support multiple resources. 


Table 4-3 Views supporting multiple resources 


View name 

Supported CICS resources 

TD Queues 

► EXTRATDQ 


► INDTDQ 


► INTRATDQ 


► REMTDQ 

Files 

► LOCFILE 


► REMFILE 

Transactions 

► LOCTRAN 


► REMTRAN 


Performing actions 

You can perform actions on resources from the Resources View by right-clicking 
and selecting the action that you want to perform from the context menu. Actions 
can be performed on a selection of multiple resources in a similar way. Actions 
can only be performed where supported by the underlying connection, which 
means that you must have a CMCI connection or the actions are disabled in the 
menus. 

Upon a request to perform an action, the CICS Explorer presents you with a 
confirmation dialog, as shown in Figure 4-12 on page 94, which displays the 
selected resource names and the action to be performed. 
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Figure 4-12 Perform action confirmation dialog 


Clicking OK attempts to perform the action on the displayed list of 
resources — one by one. If too many resources are selected to list, the total 
number of resources is displayed instead. A progress bar and status message 
are displayed as the explorer performs the action. The Cancel button remains 
available to halt action processing part-way through. 

CICS Explorer stops processing actions if any action fails. When action 
processing is completed, the results are displayed in the dialog, and a status 
message for each action is written to the status bar and the error log. Figure 4-13 
on page 95 is an example of an action processing failure message. 


Stopping the Explorer: An action processing failure or cancelling action 
processing stops the Explorer from carrying out any further actions. It will not 
undo the effect of actions that already processed. 
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Figure 4-13 Action processing failure 

Installing definitions 

To install CICS definitions: 

1 . Right-click, and select Install from the context menu. The Install dialog shows 
a list of all valid install targets, which includes system groups and managed 
regions, as shown in Figure 4-14. 



Figure 4-14 Install dialog 


2. Select an install target, and click OK to install the definition into the selected 
target. Successful installation results in a confirmation message being written 
to the error log. If the install fails, an error message is displayed in the status 
bar and in the error log. 
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Editing CICS Resources 

You can open CICS Resources in an editor by right-clicking and selecting Open; 
alternately, you can double-click the resource. If the connection that is used to 
retrieve the resource is a CMCI connection, the resource is made modifiable in 
the resulting editor. If the underlying connection is through the CICSPlex SM 
Data Interface, the editor opens in a read-only mode. 


4.4.1 Properties view 

The Properties view, shown in Figure 4-15, displays a table of attributes for the 
last selected CICS Resource. The attributes are displayed by category. Changing 
the selection in any Resources View causes the Properties View to update itself 
to display the attributes for the newly selected resource. 
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Figure 4-15 Properties view 


4.4.2 Status bar and Error Log 

The status bar and the Error Log view communicate feedback to you about the 
success or failure of operations. The status bar is located at the bottom of the 
Explorer window, as shown in Figure 4-16 on page 97. 
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Figure 4-16 Status bar location 


To open the Error Log view, click Window ->• Show View Error Log, and 
information is displayed about the result of CICS operations and CICS Explorer 
state. Figure 4-17 shows the Error Log view. 



Figure 4-17 Error Log View 


4.5 Editors 

Using the CICS Object Editor you can make modifications to objects in CICS. 
You can open most CICS objects in an editor from the CICS Object view by 
double-clicking or right-clicking and selecting Open. 

When you open an editor for a CICS object, CICS Explorer attempts to retrieve 
the latest version of that object from the server before displaying it in an editor, 
which makes sure that no stale data is represented. If the latest version of an 
object cannot be retrieved (for example, a TASK object no longer exists since the 
Tasks view was last refreshed), CICS Explorer opens an editor on the cached 
data in read-only mode. 

Figure 4-18 on page 98 shows the CICS Object Editor. 
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The CICS Object Editor comprises one or more pages that provide different 
mechanisms for modifying the values of attributes on the target object. Changes 
are made to the state of the representation of the object in the Explorer. When 
you are happy with the changes, you can save the CICS object, which applies the 
changes to the object in CICS. The server sends feedback that pertains to the 
outcome of the attempted update: either the changes were applied successfully 
or there were problems performing the update. The CICS Object Editor reflects 
the outcome by displaying a message in the status bar and in the case of errors, 
where possible, updates the editor pages to indicate which attribute(s) caused 
the problem. 

If an editor has local changes that were not yet saved to the server, the editor is 
said to be in dirty state. This state is indicated by an asterisk at the start of the 
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editor title, as shown in Figure 4-1 9. The save action for an editor is only enabled 
when it is in a dirty state. When performing an update, the only attributes that the 
Explorer sends to CICS are those that were modified. 


Figure 4-19 Editor in dirty state 

All CICS objects can be manipulated using the attributes page. 

Attributes page 

The attributes page, shown in Figure 4-21 on page 100, displays a categorized 
list of attributes that are available on a CICS object, and their values, similar to 
the Properties view. The attributes page differs from the Properties view in that it 
provides an interface for manipulating the values. Attributes with the name in 
black can be modified, whereas attributes with the name in gray cannot. The 
attributes page contains a button on the toolbar, shown in Figure 4-20, to toggle 
the display of non-editable attributes. 


Figure 4-20 Toggle Show/Hide Non-mutable attributes icon 

Click in the right column for a given attribute (or press Enter when the row has 
the focus) to modify the attribute’s value. The editor used is appropriate for the 
type of attribute that is being modified: Attributes that represent CVDA/EYUDA 
values are edited using a combo box, and everything else is edited using a text 
box. Press Enter or otherwise force the focus out of the cell to apply the entered 
value. 

Textbox cell editors use information about the underlying attribute to perform 
validation on any input without having to send the information to CICS. The net 
effect of this is that you are notified of simple validation errors as you type, on a 
key stroke-by-key stroke basis. The error is reflected by highlighting the cell with 
the editor in, and displaying an error feedback message in the page title area, as 
shown in Figure 4-21 on page 100. Attempting to apply the value for the text 
editor at this stage reverts the attribute back to its initial value. 
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Figure 4-21 Attributes page validation feedback 


Attributes that were modified since the last save are highlighted on the attributes 
page by setting the attribute name font to bold and prefixing it with a chevron, as 
shown in Figure 4-22. 



Figure 4-22 Modified attribute highlighting 


The list of attributes on an attributes page is filtered. Attributes that are not 
supported by the CICS region that the object originated from (for example, they 
were introduced in a newer release) are removed from the list. 

Rich editor pages 

In addition to the attributes page, eight CICS objects have specific pages that are 
designed to allow interaction with the attributes on a higher level: DB2 
Transaction Definition, Document Template Definition, File Definition, Pipeline 
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Definition, Process Type Definition, Program Definition, TD Queue Definition, 
Transaction Definition. 

Figure 4-23 shows the File Definition Editor overview page. 



Figure 4-23 File Definition Editor overview page 


The rich editor pages are designed to make it easier for you to understand the 
effect of manipulating specific CICS attributes, which is achieved by 
mechanisms, such as providing descriptions of what the attribute is used for, 
where appropriate, grouping logically connected attributes, and providing user 
interface that guides you away from setting conflicting values. 

The same key stroke validation that is on the attributes page is present in text 
boxes on rich editor pages. 
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The rich editor validation behavior differs from the attributes page in that the 
attribute value is not reverted when the text box loses focus; instead, the 
erroneous state is maintained until you correct it. The ability to save changes to a 
CICS object is suppressed while there are outstanding errors on any rich editor 
page. Figure 4-24 shows rich editor validation feedback. 

Click the error feedback message in the page title area to link back to the 
attribute that is responsible for the error. The link back reveals the appropriate 
page and gives the keyboard focus to the text box. 



Figure 4-24 Rich editor validation feedback 


Field-level help 

Both the attributes page and rich editor pages support showing help that is 
appropriate to the CICS attribute currently being edited. Press FI on Windows or 
Ctrl + FI on Linux to open the help that is associated with the current view within 
the Explorer. If you perform this key stroke within a CICS object editor when a 
specific attribute has the keyboard focus, the Explorer opens the help, if it is not 
already open, and displays help that is specific to that attribute. 

Server error feedback 

When you save from within a CICS object editor, the Explorer tells CICS to 
update the attributes that were modified. This operation can either succeed or fail 
in a variety of ways. All results are communicated through the status bar; 
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however, for some types of failure, the CICS object editor can display specific 
information about the failure. 

The CICS Explorer performs basic validation on the values that are supplied for 
CICS attributes at a generic, low level, for example, the Explorer typically 
performs validation, such as string length or numeric range. For any attribute, 
CICS performs more specific validation, for instance the value might be required 
to be a valid HFS path or must adhere to some relationship with another attribute. 
Any of these types of validation failure result in an update failure after saving in 
the Explorer. 

In cases like these, the CICS object editor highlights the attributes that are 
responsible for the failure in both rich editor pages and the attributes page and 
displays any error message in the page title area. Figure 4-25 shows the server 
error indication icon. 

H 

Figure 4-25 Server Error Indication icon 

Figure 4-26 shows the rich editor page server error feedback. 



Figure 4-26 Rich Editor Page Server Error feedback 


Figure 4-27 on page 104 shows the attributes page server error feedback. 
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Figure 4-27 Attributes Page Server Error feedback 


In this case, the error is caused by the Configuration File attribute not being a 
valid HFS path. 

Server errors do not suppress the save action; therefore, the responsible 
attributes can be rectified. You can resave the object. 

Update failures also result in a warning being appended to the error log with the 
full error returned from the server. 


4.6 Creating new definitions 

CICS Explorer provides a set of wizards for creating new resource definitions in 
CICS: 

► To access the resource definition creation wizards, select Explorer New 
Wizards, and either select from the subset provided or select Other to display 
the New dialog. 

► Wizards for creating resource definitions are in the CICS SM Administration 
group. To open a new definition wizard from a CICS resource view, for the 
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type of CICS object being viewed, right-click anywhere on the table, and 
select New. 

Figure 4-28 shows the new definition wizard page. 



Figure 4-28 New definition wizard anatomy 

The Data Repository is the location in which the definition will be created. This 
field is mandatory; however, if you start the wizard from the context menu in a 
resource definition view, it is populated with the context from that view. The value 
of the field must represent a valid repository and is validated by the Explorer 
against a list of valid repositories that are retrieved from the server. When the 
Data Repository field has the keyboard focus, press Ctrl + Space to activate 
content assist, which provides a list of all potential repositories for the definition. 

In the Resource Group field, you can specify a group for the definition to be 
created in. 

While all resource definitions require a name to be specified on creation, and 
optionally a description, many have additional attributes that are mandatory on 
creation. Controls representing these attributes are in the definition-specific input 
field area, such as the Data Set Name field, which we show on the pipeline 
definition creation wizard in Figure 4-28. 
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Definition creation wizards have a similar validation mechanism to the CICS 
object editor. Fields that fail validation are highlighted with an Error icon, as 
shown in Figure 4-29. A message that describes the failure is displayed in the 
notification area. 



Figure 4-29 Validation in a definition creation wizard 


When all mandatory fields are completed, and no validation errors exist, the 
Finish button becomes enabled. Click Finish to create the definition in the 
specified repository. If the create fails, an error message that is associated with 
the failure is displayed. Where a specific attribute is responsible for the failure, 
CICS Explorer also highlights that attribute in the creation wizard, as shown in 
Figure 4-30 on page 107. 
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Figure 4-30 Creation server error 

In Figure 4-30, the create failed because the Data Set Name is longer than the 
allowed 60 characters. 

Select the Open Editor option to tell the Explorer to open a successfully created 
definition in a CICS object editor. 
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5 


CICS Explorer navigation 
walkthrough 


The intent of this chapter is to provide insight into CICS Explorer navigation. The 
hands-on approach provides a script that can be followed in real-life. Whether 
doing the actual walkthrough or just reading through the chapter, the result is a 
firm understanding of CICS Explorer navigation. 
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5.1 Navigation topics covered 


In this section, we discuss how to: 

► Manipulate views, columns, filters, and perspectives. This discussion includes 
positioning the views and their components, positioning, adding, and deleting 
columns, filters, and perspectives, and also creating perspectives. 

► Perform common operations functions against CICS resources. 

► Perform common resource administration functions against traditional CSD 
and CICSPLex Business Application Services (BAS) resources. 


5.2 Manipulating views 

In this section, we discuss how to manipulate views. 


5.2.1 Adding a view 

To add a view: 

1 . Start CICS Explorer and connect using a CMCI connection. You can use the 
CICSPlex SM Data Interface connection, but CMCI is needed for other 
sections of the walkthrough. 

2. Add the Programs view by going to the Operations Menu and clicking 
Programs, as shown in Figure 5-1 on page 111. 
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Figure 5-1 Adda view selection 


The Programs view is added, as shown in Figure 5-2. 


| & ClCSdex ExdI X ft) CICSolex Reo I ° □ 1 1 ^ Regions f fti Tasks f Ftfl I5C/MRO Connections I S Terminals I HP Files f fc Transactions feLii.:. . 
Server: CPSM ^Tj piX0211I Context: CICSPLX1. Resource: PROGRAM. 31,209 records collected at Sep 7, 2oio9-4??77ffl 


Figure 5-2 Add a view result 


Note: If you click the X (on the Programs view tab) the Programs view is 
removed. 
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5.2.2 Zooming in and out of a view 


To zoom in and out of a view: 

1 . To zoom in on the Programs view, double-click the Programs tab. Avoid the 
X. The Programs view now fills the entire window, as shown in Figure 5-3. 



2. To zoom out, double-click the Programs view tab again. Avoid clicking the X. 


5.2.3 Refreshing a view 

To refresh a view, either click Refresh for the view, as shown in Figure 5-4 on 
page 1 1 3, or press Enter. 
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Figure 5-4 Refresh Icon locations 


Refresh icons: The Refresh icon on the left refreshes the currently selected 
CICSplex Explorer view. The Refresh icon on the right refreshes the currently 
selected Programs view. 


5.2.4 Resizing a view 

To resize a view: 

1 . Position your cursor at the border of a view, as shown in Figure 5-5. When 
positioned correctly, your cursor becomes a vertical or horizontal double 
arrow. 



Figure 5-5 Resize a view 
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2. Click and drag to achieve the desired size. 


5.2.5 Repositioning a view 

To change the position of a view: 

1 . Click the View tab and drag it to the desired location. As you are dragging the 
view, your cursor will change to one of the following icons in Figure 5-6. 


Cursor 

Where the View will be moved 

t 

Position above the Current View (the View that 
is underneath the cursor) 

* 

Position Below the Current View 

* 

Position to the Right of the Current View 


Position to the Left of the Current View 

fiP 

Stack: The View is stacked as a Tab in the 
Current View 

0 

Restricted: Cannot be positioned in Current 
Area 

H 

Open a New Window. Drag outside the 
workbench to position in a new window. Note: 
Click the New Window and drag back to 
position it back. 


Figure 5-6 Cursor designations 


2. Click the Programs tab, as shown in Figure 5-7 on page 115, and drag it to 
the right of the window. When your cursor becomes a right arrow, release it. 
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The Programs view is now next to the Regions view. 


Returning the Programs view: To put the Programs view back in its original 
position, click the Programs tab, and drag it to the center of the Regions view. 
When your cursor changes to a stack, release it. 


5.3 Manipulating columns 

In this section, we discuss how you can manipulate columns. 

5.3.1 Customizing columns 

To customize columns: 

1 . Select the Programs view. 

2. Click the View menu, and select Customize Columns, as shown in 
Figure 5-8 on page 116. 
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Figure 5-8 View Menu location 


The Customize Columns dialog box is displayed, as shown in Figure 5-9. 



3. Under the Available attributes select Change User ID, as shown in 
Figure 5-9. 

4. Click Add. The Change User ID is added to the end of the Programs view 
columns. 

5. Under Current viewer columns, select Share Status. 

6. Click Remove. The Share Status is removed from the Programs view 
columns. 
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7. Click Reset. The default columns, for the Programs view, are now restored, 
and the: 

- Change User ID is no longer there 

- Share Status has been added back 

8. Click Close to close the dialog box. 

5.3.2 Repositioning columns 

To change the order of the columns: 

1 . Click and drag the column to the desired location. 

2. From the Programs view, click the Language column, and drag it between the 
Name and Status columns, as shown in Figure 5-10. The Language column is 
now positioned between the Name and Status columns. 



Figure 5-10 Reposition Language column 


5.3.3 Resizing columns 

To resize a column: 

1 . Position your cursor at the border of the column. When your cursor turns into 
a horizontal double arrow, bisected by a vertical line, you can click and drag 
the column border to the desired width. 

2. From the Programs view, position your cursor on the border of the Use Count 
column, as shown in Figure 5-1 1 . 

3. Click and drag the column border, expanding the column width. 



Figure 5-11 Resize Use Count column 
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5.3.4 Equalizing column widths 


To make all of the columns the same width: 

1 . From the Programs view, click the View menu. 

2. Select Equalize Column Widths. All the columns are now of equal width, 
including the Use Count column. 



Figure 5-12 Equalize column widths 


5.3.5 Resetting columns 

Resetting the columns will restore all of the columns to the default location, size, 
and so on: 

1 . From the Programs view, click the View menu. 

2. Select Reset columns. All the columns are back in their starting state, 
including the location of Language 


5.4 Manipulating filters 

In this section, we show you how to filter your information. 

5.4.1 Using filters 

Filters set the search criteria for the CICS resources that you want to display. To 
use the filters: 

1 . Click the Programs tab. 

2. In the Name field, type DFH*, as shown in Figure 5-1 3 on page 1 1 9, and either 
press Enter or click Refresh. Now, only programs beginning with DFH* are 
displayed. 
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Figure 5-13 Using a program name filter of DFH* 


5.4.2 Customizing filters 

To customize filters: 

1 . In the Programs view, click the View Menu, and select Choose filter attributes, 
as illustrated in Figure 5-14. 



Figure 5-14 Choose filter attributes 
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In Figure 5-14 on page 119, notice that: 

- The Region is unavailable, indicating that it cannot be used as a filter for 
the Programs view. 

- Name has a check mark next to it, indicating that the Name filter is already 
part of the view. 

- You can see a list of the other, currently available filters. 

2. Click the available Language filter, and notice that: 

- The Language filter now has a check mark next to it. 

- The Language filter is next to the Name filter in the view. 

3. Leave the Name filter set to DHF*, and set the Language filter to Cobol . Use 
the Language filter drop-down menu to set it. 

4. Refresh the window. Use the Refresh icon, Enter, or the Apply filter icon, 
shown in Figure 5-15, to refresh. 



Figure 5-15 Add Language filter 


As a result, only COBOL programs that start with DFH* are displayed. 

5. To remove an existing filter, go to the View Menu, click Filter Attributes, and 
deselect it. 


5.5 Manipulating perspectives 

If you log off of CICS Explorer, all of the settings (view additions/deletions, 
column settings, filters, and so on) that are in place at logoff time are preserved 
in your individual CICS Explorer workspace file. At logon time you return to the 
exact same display configuration. 

Perspectives can be used to save a set of screen settings, so that you can 
manipulate your working screen settings, but still return to a desired screen 
configuration at any time. As with any customization, perspectives are saved to 
the your individual workspace file. 
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5.5.1 Creating a perspective 


To create a perspective: 

1 . Click the Programs tab, open the Window menu, and select Save 
Perspective as. 

2. When prompted for a Name type CICS NavLab, and click OK, as illustrated in 
Figure 5-16. 



Figure 5-16 Save Perspective /As dialog box 


5.5.2 Opening a perspective 

The current perspective is highlighted in the shortcut bar. There are three ways 
that you can open a perspective: 

► Access the Open Perspective screen by selecting the Window tab -» Open 
Perspective -» Other. 

► Access the Open Perspective screen by clicking the Open Perspective Icon, 
and selecting Other. 

► Click the desired perspective button from the shortcut bar. 
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The new CICS NavLab perspective might not show up on the shortcut bar until 
you toggle to the CICS SM (default) perspective, as shown in Figure 5-17. 



Figure 5-17 Methods for opening a perspective 


When you open the CICS SM (default) perspective, notice that the CICS SM 
(default) perspective is now in the state it was in prior to the walkthrough, for 
example, the Programs view is no longer there. 

Reopen the CICS NavLab Perspective. All of the customization you applied 
during the walkthrough is still included in that perspective. 

5.5.3 Resetting a perspective 

You can reset a perspective, to its default settings by selecting the Window menu 
and choosing Reset Perspective. 

1 . From the CICS NavLab Perspective, select the Operations menu, and add 
the RPL List view. 

2. Reset the CICS NavLab Perspective by selecting the Window menu and 
choosing Reset Perspective. The RPL List view is removed and all other 
customization (Programs view, filters, and so on) in place, at the time the 
CICS NavLab perspective was created, are still there. 
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5.5.4 Deleting a perspective 

To delete a perspective: 

1 . Make a copy of the CICS NavLab perspective 

a. From the CICS NavLab perspective, select the Window menu and choose 
Save Perspective As. 

b. Enter a Name of “CICS NavLab2”. 

2. Reopen the CICS NavLab perspective 

a. We are going to delete the new CICS NavLab2 perspective and it 
shouldn’t be active at the time of deletion. 

3. Select the Window menu, and choose Preferences. 

4. Expand Eclipse Platform. 

5. Select Perspectives. 

6. Select the CICS NavLab2 perspective. 

7. Click Delete. 

8. Click Yes to confirm deletion. 

9. Click OK to close the Preferences dialog 
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Figure 5-18 Delete perspective 


5.6 Performing operations functions 

You must be connected using a CMCI connection, and have security 
authorization to perform the following tasks. 


5.6.1 Performing a program Newcopy 

In this section, we work with resources that are associated with the IBM NACT 
sample application: 

1 . From the Programs view: 

a. Set your Name filter to DFH0CNA1. 

b. You can use a Language filter of COBOL or leave that field empty. 
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2. Refresh your window. 

3. Select all instances/region entries for the DFH0CNA1 program: 

a. Click the first entry. 

b. Hold down the Shift key, and click the last entry. 

c. To select individual entries, that are not next to each other 

i. Click the first entry. 

ii. Hold down the Ctrl key, and click each subsequent entry to select it. 

4. With all desired instances selected, right-click, and select New Copy. 

5. From the Perform Operation dialog window, click OK to confirm that you want 
to Newcopy all the entries, as shown in Figure 5-19. 



Figure 5-19 Perform Operations dialog box 


Individual Newcopy results: 

► A green check mark appears next to each successful Newcopy. 

► A red X appears next to each unsuccessful Newcopy. Associated error details 
are provided. 
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5.6.2 Altering CICS region MAXTASKS 


To alter CICS region MAXTASKS: 

1 . Select the Regions view. 

2. Double-click to select a desired Region. A window is displayed that details the 
Region Attributes. 

3. Scroll down to the Transaction Activity attributes, and increase Maximum 
Tasks by 5. 

4. Press Enter. As soon as you press Enter a “>” is displayed next to Maximum 
Tasks, which indicates that there is a pending change. 

5. Click Save to make the change, as shown in Figure 5-20. 



Figure 5-20 Change CICS region MAXTASKS 


126 IBM CICS Explorer 


5.7 Performing administration functions 


In this section, we work with CICS resources that are contained in the CSD and 
resources housed in the CICSPlex Data Repository as part of the CICSPlex BAS 
component. 

CICSPlex BAS (Business Application Services) is an alternative method for 
deploying CICS resources. Resources are housed in the CPSM Data Repository 
and installed through EXEC CICS CREATE commands. 


CICS CSD CPSM BAS 



Figure 5-21 Resource Repository: CICS CSD versus CPSM BAS 


Note: The Scope you choose determines where the resources are with which 
you are working: 

► If scope equals the entire CICSplex you are working with BAS resources. 

► If scope equals an individual CICS region, you are working with resources 
contained within that specific region CSD. 


You must be connected using a CMCI connection and have security 
authorization. 
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In this section, CICSPlex BAS resources are dynamically installed. To set up the 

install of BAS resources, at region startup time, additional BAS resources must 

be defined. See the CICS TS Manual for full details. 

5.7.1 Viewing CSD resources 

To view CSD resources: 

1 . Choose a scope that is equal to an individual region. 

2. Add the Group List Definition view: 

a. Open the Administration menu, and select Group List Definitions. With 
the scope set to an individual region, the display shows CICS group lists in 
the region CSD (CSDLIST). 

3. Add the Resource Group Definition view: 

a. Open the Administration menu, and select Resource Group 

Definitions. The display shows CICS groups in the individual region CSD 
(CSDGROUP) 

4. Add the Program Definitions view: 

a. Open the Administration menu, and select Program Definitions. 

b. From the View menu, select Customize Columns. 

c. Select the CSDGroup attribute, and click Add, to add it to the Program 
Definitions view. 

d. Click Close to close the Customize Columns dialog. 

Figure 5-22 on page 129 shows the CSD resources views. 
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Figure 5-22 View CSD resources 


5.7.2 Creating CSD resources 

To create resources, use the CICS Explorer New Wizard: 

1 . There are a few methods for opening the New Wizard: 

- Click the down arrow for the New Wizard icon. 

- From the CICSplex Explorer view, select a scope, right-click, and select 

New. 

- Open a resource definition view (example: The Program Definitions view), 
right-click (in the view), and select New. 

- Open the Explorer menu, and select New Wizards, as shown in 
Figure 5-23 on page 130. 


Chapter 5. CICS Explorer navigation walkthrough 129 


5 



5-23 New Wizards 


2. Create a CSD Program definition in a New CSD Group: 

a. Confirm that your scope is still set to an individual region. 

b. Select Explorer ->• New Wizards ->■ Program Definition. 

c. Set the values for the Program definition, as shown in Figure 5-24. 



Figure 5-24 New Program Definition dialog box 


d. Click Finish. 

3. View the results, as shown in Figure 5-25 on page 1 31 : 

a. Click X to close the Program Definition Overview. 

b. Set the Program Definitions view Name filter to NAV*. 
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c. Set the Resource Group Definitions view filter to NAV*. 

d. Refresh the views. 



= □ 

’rograrn Definition (NAVCSDPG) NavLab CSD Program Def 

m Overview 

□ 

Basic 

Name: NAVCSDPG Description: | NavLab CSD Program Def 

CSD Group: NAVCSDGP Created: Sep 14, 2010 9:15:38 AM j 

0 Enabled Changed: Sep 14, 2010 9:15:38 AM 

i 

Details 

Language: [nJa 3 D Non ' CICS (0pen) API 

□ Threadsafe (able to use open TCB ) 

0 Display Execution Diagnostic Facility (EDF) screens 


Storage 

□ Can handle 31 bit addresses (above the 16MB line) 

□ Use Program from the Link Pack Area (LPA) 
l~l Program can write to CICS-key storage 

Program reuse The NAVCSDPG PrC 

© Reuse if possible Definition has been 

O Force reuse in the New NAVCSD 

O Always load a new copy CSDGROUP 
O Load a new copy whenever use count drops to zero 

>gram 

created 

GP 


Figure 5-25 Program definition overview 


Figure 5-26 on page 132 shows the display of new CSD program definition. 
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Figure 5-26 Display of new CSD program definition 


5.7.3 Installing CSD resources 

To install CSD resources: 

1 . Verify that you have the same single region scope selected that was used 
during the creation of the NAVCSDPG Program Definition. 

2. From the Program Definitions view, right-click the NAVCSDPG Program 
Definition, click install, as shown in Figure 5-27 on page 133, and select the 

Single Region Target. Click OK. 
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Figure 5-27 Perform CSD program definition install 


3. From the Programs view: 

a. Set the Name filter to NAV*. 

b. Set the Language filter to NOTDEFINED. 

c. Refresh the view. You will see the NAVCSDPG Program installed in the 
single, target scope region 

5.7.4 Creating BAS resources 

In the event that there are no BAS resources currently defined, you can create 
new BAS resources, prior to viewing: 

1 . Set the scope to an appropriate CICSplex, rather than an individual region. 

2. Create a New BAS resource group. Unlike the creation of CSD Resources, 
the BAS resource group must exist before resources can be added to it: 

a. From the Resource Group Definitions view: 

i. Right-click inside the view, and select New. 

ii. Select Resource Group Definition. 
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iii. Set the Create Resource Group Definition attributes to the those 
shown in Figure 5-28, and click Finish. The Resource Group Definition 
attributes view is displayed, confirming the creation of the new BAS 
Resource Group. NAVBASGP is displayed in the Resource Group 
Definitions view. 



3. Click X to close the Resource Group Definition (NAVBASGP) Attributes view. 

4. Create the new BAS program definition in the new BAS NAVBASGP 
Resource Group: 

a. Select Explorer ->• New Wizards -» Program Definition: 

i. Set the Data Repository to the CICSplex scope. 
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ii. Do not select the Region CSD option. 

iii. Set Resource Group to NAVBASGP. 

iv. Set Name to NAVBASPG. 

v. Set Description to NavLab BAS Program Def. 

vi. Click Finish, 
b. Notice that: 

i. The Program Definition (NAVBASPG) Overview is displayed, 
confirming creation of the new BAS Program Definition. 

ii. When you select the Program Definitions view, the new NAVBASPG 
program definition will be displayed. 

5. Click X to close the Program Definition (NAVBASPG) Overview. 

5.7.5 Viewing the BAS resources 

To view the BAS resources: 

1 . Confirm that you still have the appropriate CICSplex selected, as your scope. 

2. Refresh your views, as shown in Figure 5-29. 



Figure 5-29 BAS program definition display 
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5.7.6 Installing BAS resources 

To install BAS resources: 

1 . Confirm that you still have the CICSplex set as your scope. 

2. From the Program Definitions view, right-click the NAVBASPG Program 
Definition, and select Install. You are presented with a list of CICS Regions 
that are currently active in the CICSplex. 

3. Select the appropriate Target(s), and click OK. 

4. Select and refresh the Programs view. 

5. Confirm that the Name filter is still set to NAV*. 

6. Confirm that the Language filter is still set to NOTDEFINED. 

The NAVBASPG Program Definition is now installed in the Target(s) you 
selected. 


5.8 Summary 

You now have a solid working knowledge of CICS Explorer Navigation. 

The walkthrough provided detailed information regarding: 

► View manipulation 

► View column manipulation 

► View filter manipulation 

► Perspective manipulation 

► Performance of operations functions 

► Performance of administration functions, against CSD and BAS Resources 
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CICS Explorer IA plug-in 
familiarization 

The CICS Explorer IA plug-in provides a graphical user interface (GUI) to CICS 
IA that runs toolbar searches on common resources and helps you to build 
detailed queries to interrogate the Dependency and Affinity database objects. 
The CICS IA plug-in also provides a number of sample queries. 


© Copyright IBM Corp. 2010. All rights reserved. 
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6.1 CICS IA introduction 


IBM CICS Interdependency Analyzer for z/OS V2.2 identifies resource 

interdependencies in your CICS systems, automates detection of your CICS 

runtime relationships, records data in a DB2 database, and helps you analyze 

the collected information for use in your daily processes. 

Some benefits of CICS IA are: 

► The resources that are identified by this runtime tool are those that are 
associated with transactions, programs, Basic Mapping Support maps, files, 
temporary storage queues, transient data (TD) queues, 3270 Bridge facility, 
web services, CorbaServer, and Enterprise JavaBeans (EJBs). 

► Reports on DB2, IMS, and WebSphere MQ resources that CICS uses are 
also generated. 

► A CICS IA plug-in is now available for the CICS Explorer to offer the same 
intuitive way to query CICS relationship data, manage queries, and navigate 
through complex application relationships, now from a standard interface. 

► The CICS IA plug-in integrates with other CICS Explorer perspectives, for 
example, to click a transaction in a CICS PA bar chart and drill right-down to 
see its dependencies, relationships, affinities, and more. 

► Sample queries assist you by highlighting those applications that are currently 
running in previous levels of CICS TS that are most sensitive to CICS API and 
SPI command changes. 

► Version 2.2 includes support for modernizing your key CICS applications for 
deployment in a service-oriented architecture (SOA) by identifying 
applications that are suitable for exposure as web services, and it provides 
initial integration with WebSphere Studio Asset Analyzer. 

► Support for CICS resources used by Software AG Natural gives you new 
insight into the behavior of your Natural applications. 
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6.2 What CICS IA can do for you 


There are many business reasons for using CICS IA and they vary by industry. 

Here are some of the business imperatives facing corporations today: 

► Mergers and acquisitions 

Many banks are involved in mergers and acquisitions. The result is that they 
must consolidate workloads and move CICS applications around for isolation 
reasons or to spread the workload for performance reasons. Because these 
applications might not be well understood by the acquiring bank and 
documentation might be inadequate, there is a need to understand all of the 
resources that are associated with a given application. 

► Outsourcing 

Large outsourcing companies are continually facing the problem of running 
CICS applications with which they are unfamiliar. Often, naming standards 
are lacking or conflict with other applications that are running on the same 
LPAR. Documentation might be nonexistent or incomplete. Again, there is a 
need for a tool to facilitate the understanding of the resource 
interdependencies and affinities that are involved. 

► Maintenance or enhancement of applications 

During the normal application life cycle, CICS applications require 
maintenance and enhancement. When a programmer who is unfamiliar with 
the application that they are required to modify starts the modification 
process, much time can be spent trying to understand the application and the 
inherent flow of transactions. This learning curve can be greatly reduced 
using CICS IA, which identifies the resources that are affected directly and 
indirectly. 

6.2.1 CICS IA highlights 

Using CICS IA you can: 

► Automate detection of runtime resource relationships 

► Understand application flow with flexible resource-relationship reports 

► Accumulate resource-relationship data in a DB2 database 

► Build relationship maps to help improve the speed of application maintenance 
and to help reduce the time to resolve problems 

► Compare applications and resources across regions 

► Migrate, reuse, and extend CICS applications more quickly 

► Support SOA implementations with deep application understanding 
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► Make informed decisions about the best way to split workloads 

► Minimize the impact of routine application maintenance for the user 


6.2.2 The questions that CICS IA can answer 

These are some of the questions that can be answered with CICS IA, and we 
offer them to give you a sense of what is possible with CICS IA: 

► What region(s) does a particular CICS application run in? 

► What are all of the CICS resources used by a given application? 

► What are all of the CICS resources used by a given transaction? 

► What transactions belong to a given application? 

► What programs does a given transaction invoke? 

► What transactions access a particular file and how? 

► What resources are used by a specific program? 

► How is a file accessed by a particular program? 

► Which affinities does a transaction have? 

► How do you query on DB2, MQ, or IMS resource use? 


6.3 Description of CICS IA 

IBM CICS Interdependency Analyzer for z/OS is the IBM discovery tool for CICS 
Transaction Server for z/OS, offering a wide range of new capabilities and 
supporting completely new functions in CICS Transaction Server, Version 3.2. 
New capabilities, such as threadsafe and affinity analysis, a new user interface, 
and support for Software AG Natural, make it possible to achieve better reuse, 
management, and control of your applications through improved understanding 
of an even wider range of CICS systems and resources. CICS Interdependency 
Analyzer facilitates projects, such as CICS version-to-version migration, affinity 
removal, and Web service refactoring that depend on deep knowledge of 
application, system, and resource relationships for their success. 

CICS IA is a runtime and batch system for use with CICS Transaction Server for 
z/OS and CICS Transaction Server for OS/390®. It has two purposes: 

► To identify CICS application resources and their interdependencies. 

This function enables you to understand the makeup of your application set, 
such as: 

- Which transactions use which programs 

- Which programs use which resources (files, maps, queues) 

- Which resources are no longer used 

- What applications does a CICS region contain 
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CICS IA captures interdependency information while CICS is running and 
stores it in VSAM files. Detailed reports can be produced from the VSAM files, 
if desired. Subsequently, the VSAM files load the DB2 database. 

► To analyze transaction affinities 

Affinities require particular groups of transactions to be run either in the same 
CICS region or in a particular region. 

Affinities information is useful in a dynamic routing environment because you 
must know of any restrictions that prevent particular transactions from being 
routed to particular application-owning regions (AORs) or that require 
particular transactions to be routed to particular AORs. 

CICS IA captures and loads the Affinity data into its DB2 databases. The data 
can then be queried with the CICS IA plug-in, the CICS IA online transaction 
CINQ, with batch SQL queries, or with other SQL query software tools. 
Through batch SQL processing, detailed reports can be produced. 

Many large organizations have used CICS since the early 1970s, their systems 
growing and evolving with the business. During this time, many techniques of 
implementing applications were used — as a result of new function, changing 
corporate standards, technical requirements, and business pressures. 

Frequently, this growth was not as structured as it might have been with the result 
that many applications and services share common resources and changes in 
one area typically affect many other areas. This issue can reach such a level that 
the system can no longer develop in a controlled manner without a full 
understanding of these interrelationships. CICS IA can help you achieve this 
understanding, for example, if you need to change the content or structure of a 
file, you must know which programs use this file because they must be changed 
too. CICS IA can tell you this information and the transactions that drive the 
programs. CICS IA records the interdependencies between resources (such as 
files, programs, and transactions) by monitoring programming commands that 
operate on resources. 

The application that issues such a command has a dependency on the resource 
that is named in the command, for example, if an application program issues the 
command EXEC CICS WRITE FILE ( myfile ), it has a dependency on the file 
called myfile. It might have similar dependencies on transient data queues, 
temporary storage queues, transactions, other programs, and so on. 

The commands that are monitored are typically CICS application programming 
interface (API) and system programming interface (SPI) commands that operate 
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on CICS resources; however, you can also instruct CICS IA to monitor some 
types of non-CICS command that operate on non-CICS resources; for example: 

► MQ calls to WebSphere MQ resources 

► EXEC DLI calls to IMS database resources 

► DB2 calls 

► Dynamic COBOL calls to other programs 

Potentially, the inclusion of any non-CICS resources gives you a fuller picture of 
the resources that a transaction uses. 

The Collector component of CICS IA collects the dependencies that apply to a 
single CICS region, that is, a single application-owning region (AOR) or a single, 
combined routing region-AOR. It can be run against production CICS regions 
and is also useful in a test environment to monitor possible dependencies that 
new or changed application suites or packages introduce. 

From the interactive interface of CICS IA you can control Collectors running on 
multiple regions. 


CICS IA with your entire workload: To ensure that you monitor as many 
potential dependencies as possible, use CICS IA with all parts of your 
workload, including rarely-used transactions and abnormal situations. CICS IA 
collects these dependencies into a database. You can store the dependency 
information from several CICS regions into the same database. You can 
review the collected dependencies using the CICS IA Query interface, or list 
them using the Reporter. 
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6.4 CICS IA plug-in overview 

Figure 6-1 shows all of the views that are available in the new CICS IA plug-in. 



Figure 6- 1 Views of CICS I A plug-in 


6.5 Toolbar searches and queries 

The CICS IA plug-in has two methods of interrogating data that the CICS IA 
Collector collects: toolbar searches and queries. 


6.5.1 Toolbar searches 

The CICS IA plug-in has four toolbars that you can use to search for common 
resources, programs, transactions, and regions, which you can see in Figure 6-2 
on page 144. Toolbar searching is a quick way of interrogating a limited amount 
of data because the resources that you can interrogate are fixed by the menu 
options. 

You can search by name and region only, or you can use the Regions toolbar to 
search by regions only; however you can restrict or expand the search criteria by 
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using the wildcard. The structure of the results that are displayed in the 
Resources window is also fixed. The description of the toolbar search that you 
run is shown above the results in the Resources window. You cannot save the 
results of a toolbar search. Figure 6-2 shows the toolbar search. 



6.5.2 Queries 

The CICS IA plug-in provides you with a number of defined queries, which you 
can edit, and helps you to build detailed queries of your own. When you create a 
query, you can define the structure of the results that are displayed in the 
Resources window. The structure is not fixed. You can query any resources in 
any combination. You can also add filters to the query to further refine the results. 
The description of the query that you run is shown above the results in the 
Resources window. You can save queries that you edit or create. 

When you run a query, you can save the search results in a list under the query 
name in the Queries window for future reference. You can copy the definition of a 
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query to the clipboard and paste it into the same folder, or a different folder, in the 
Query window. If you want to run your own SQL, you can paste the query 
definition into a text editor to view the raw SQL strings that run against the DB2 
tables. Figure 6-3 shows the CICS IA plug-in main window. 



Figure 6-3 Main CICS IA plug-in menu 


The Explorer has an implicit wildcard (*) that is added to the end of all search 
values. The wildcard is not visible, for example, when you search using the 
toolbar or define queries; instead, if you type FIN as a value, it is read as FIN*. 
The wildcard is denoted by the *. In this way, the search is for all resources that 
begin with FIN. 

If you require an explicit wildcard, you can add it anywhere in the search 
definition; however, the implicit wildcard at the end of the search value remains, 
for example: 

► To search for resources that begin with FIN and include 01 , enter FIN*01. 

► To search for resources that contain 01 , enter *01. 

► To narrow your search as much as you want, you can use as many wild cards 
as required, for example, A*0*3* is also acceptable. 
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The implicit wildcard is nearly always added to the end of the search value, for 
example, searching for PROG*AF can return: 


► PROGAAAF 

► PROGAAFA 

► PROGAFAA 


Note: A wildcard is not always added. If it is a transaction, and we enter FINA, 
we do not add an *. 


Use the toolbar at the top of the CICS IA plug-in to search for common 
resources. You can search by name and region only. You can restrict or expand 
the search using the wildcard. 

To run a toolbar search for common resources: 

1 . Use the menu in the Find field to select a resource to search. 

2. Use the ID field to limit the search to a particular ID, or you can leave the field 
blank. 

3. Use the Region field to limit the search to a particular region or regions. 

4. To run the search, click Search ->• Run, click the green toolbar button, or 
press Enter. The result of the search is shown in the Resources window. 


6.6 Programs and Transactions windows 

When you first open the CICS IA plug-in and connect to the database the 
information in the Programs window and Transactions window is retrieved from 
the data that is extracted to the database by the CICS IA Collector. The 
information is displayed in an alphabetic list and is static. 

You can use the toolbar search, which is located at the top of the Queries and 
Regions window, to explore the programs and transactions. Figure 6-4 on 
page 147 shows an example of the Programs and Transactions window. 

The information in the Programs window is a list of all of the programs that are 
known to CICS IA, which are: 

► Programs that are the sources of interactions 

► Programs that are the results of interactions 

► Programs that are CICS resource types 
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The information in the Transactions window is a list of all of the transactions that 
are known to IA, which are: 

► Transactions in which programs are running 

► Transactions that are the results of interactions 

► Transactions that are CICS resources of TRANSID type 



6.6.1 Searching programs and transactions 

You can search the programs that are listed in the Programs window. The data is 
stored in the database by the CICS IA Collector and is retrieved when you first 
open the CICS IA plug-in and connect to the database. 

To search the programs list for particular programs that you want to analyze 
further: 

1 . Click the Programs tab to bring the Programs window to the front. 

2. To filter the search, in the left field, enter the name of the search criteria, and 
in the Region field, enter the region search criteria. An implicit wildcard is 
appended to the end of the search criteria, and you can add wild cards at the 
beginning and in the middle. You can search by name only, region only, or 
name and region. 

3. Press Enter, or click Search ->• Run to run the search. The results are 
displayed in the Programs window. 


Transactions: This is the same process for transactions except that you 
search transactions in the Transactions window. 
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6.7 Regions window 


When you run a toolbar search or a query, the Regions window displays all of the 
regions for which the CICS IA Collector stored data in the database. The results 
are displayed in an alphabetic list. You have only one search field, which is for the 
region name. Figure 6-5 shows an example of this window. 


1 Queries ffl Regions “ O 


ffl DWBTESTA 
0IYCYZC3A 
ffllYCYZC3B 
ffl IYCYZC3C 
®IYCYZC3D 
ffl IYCYZC31 
$ IYCYZC32 
ffl IYCYZC33 
ffi IYCYZC34 
ffl IYCYZC35 
® IYCYZC36 
ffl IYCYZC37 
ffi IYCYZC38 
ffl IYCYZC39 
0IYDZZ132 
0IYDZZ222 
ffi IYDZZ232 
ffi IYDZZ312 
$IYDZZ320 
ffl IYDZZ322 


Figure 6-5 Regions window 


You can search the regions list for particular transactions that you want to 
analyze further. To search in the Regions window: 

1 . Click the Regions tab to bring the Regions window to the front. 

2. To filter the search, in the search field, enter the region name search criteria. 
An implicit wildcard is appended to the end of the search criteria, and you can 
add wildcards at the beginning and in the middle. 

3. Press Enter or click Search Run to run the search. The results are 
displayed in the Transactions window. 

4. Right-click the name of the region you want to analyze. 

5. From the menu, select the resource that you want to search. 
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6.8 Properties window 


The Properties window gives you details about programs, transactions, files, TD 
queues, TS queues, and exits, as shown in Figure 6-6 and Figure 6-7 on 
page 150. 


□ Properties £3 


\*Um ^ 

Property 

Value 

* 

a Program DRIVERP in IYDZE 
Access 

acs 


Appid 

IYDZEJ03 


Concurrency 

QUASIRENT 


Data location 

BELOW 


Dynamic status 

NOTDYNAMIC 


Execution key 

USER 


Execution set 

FULLAPI 


Exit point 
First run 

2009-06-01 12:44:53.817017 


Hold status 

TASKLIFE 


Homesysid 

EJ03 


Install type 

GROUPLIST 


Language deduced 

COBOL2 


Language defined 

NOTDEFINED 


Last run 

Lib dataset name 
Linkedit date 

0001-01-01 00:00:00.0 


Load status 

LOADABLE 


1 rvraHnn 




Figure 6-6 Properties window 
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Figure 6-7 Properties window Part 2 


6.9 Supplied queries with CICS IA plug-in 

There are a number of predefined queries that are supplied with the CICS IA 
plug-in for each resource. You can edit the queries to suit your requirements. 
Figure 6-8 on page 151 and Figure 6-9 on page 152 show examples of the 
window that you see with the queries all expanded. 
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Figure 6-8 CICS supplied queries 
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Find Resource - with ID 

in Region 

o 

Lf) Queries 0 Regions 


€) “ n 


0 Supplied Samples 
ffi & CICS 

0 &DB2 

g 9 All plans by region 
g 9 Cursor resources by region 
g 9 DB2 Resources by subsystem 
8 (£> IMS 

g 9 All IMS resources for region IYCYZC38 
g 9 All PCB usage by program and region 
g 9 All PSB resources by region 

1 9 ft MQ 

g 9 All Queues that issue a PUT1 by program 
g 9 MQ resource usage by region 
g 9 MQ resources for transaction TEST 
User Queries 

1 g 9 All programs using files 

i g 9 All transactions with potential affinities 
& New Folder 

| g 9 Resource usage by program 
; g 9 What transaction accesss file TTZSWCH 
g 8 testl 

g 9 what programs does transaction VA10 invoke 


Figure 6-9 DB2 IMS and MQ supplied queries 


To run a predefined query in the Queries window: 

1 . In the Queries window, select the resource that you want to query, as shown 
in Figure 6-10 on page 153. 

2. To view the query names, click the plus sign to expand the list of queries, as 
shown in Figure 6-1 1 on page 154. 

3. To run the query, right-click the query name, and click Run, or click the query 
you want to run, and click Search Run. The results are displayed in the 
Resources window. You can save the results for future reference and further 
analyze the results. Figure 6-12 on page 155 is an example of you clicking 
Run, and Figure 6-13 on page 155 shows the results. 

Next, we show a step-by-step example of running the supplied query: all 
transactions by region. Figure 6-10 on page 153 shows the selected CICS 
queries. 
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Next, we look at general queries underneath the CICS heading. Figure 6-1 1 on 
page 154 shows the general queries expanded. 
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Click Run to execute the query, as shown in Figure 6-12 on page 155. 
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Find Resource - with ID | ] in Region O 

Queries ffi Regions £| ° E 

0 & Supplied Samples 

0 & acs 

C+ C2* Affinities 
0 & Exits 
; 0 General 


H° All programs using files 



i 0 & DB2 
j SI & IMS 
0- & MQ 
0-(& User Queries 


Figure 6-12 Click run to execute 


Figure 6-13 shows results of the all transactions by region query. 
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6.10 Creating your own queries in the CICS IA plug-in 


To create a query: 

1 . Click Explorer ->• New, or right-click in the Queries window, and select New, 
as shown in Figure 6-14. If you want to save the query, right-click the folder 
name under which you want the query to be listed. 



2. From the menu, select the resource type that you want to query. We selected 
CICS, as shown in Figure 6-15 on page 157. 
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Figure 6-15 Create CICS query 

3. In the Create Query window, go to the Name field, and enter a query name. 
We called ours testl. 

4. In the Show panel, click the green plus sign button to select the resource or 
resources that you want to query, as shown in Figure 6-16 on page 158. 
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Figure 6-16 Query resource selection 


5. Click the red X button to remove resources. 

6. Click the yellow arrows to move the selected resources up and down the tree 
so that the query results are presented in the required order. The resources 
tree that is created from your selections is in the format in which the results 
are displayed in the Resources View when you run the query. 


6.10.1 Adding filters to the query 

When you create a query, you can further refine your query by editing the right 
pane in the Create Query window. When you select an expression, the right pane 
changes allow you to further define your query: 

1 . Select is or is not for the values in the query. If the expression that you 
selected has a known set of values, for example, Resource Type, the values 
are listed. These properties are added to the left pane so that you can view 
the query string for each line easily. If you need both is and is not values to be 
included in the query for the same resource, you require two lines for the 
same resource because you cannot combine is and is not values. 
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2. Define the expressions you selected by arbitrary values, for example, 

Resource Name. Use the editable table to define the values. These properties 
are added to the left pane so that you can easily view the query string for 
each line. An implicit wildcard is appended to the end of the value, and you 
can add wildcards at the beginning and in the middle. 

To our testl query, we selected resources as being transactions. We then further 
filtered this down to being a particular transaction. So for the filter, we select 
Transaction. We then select transaction is EMS1, as shown in Figure 6-17. 



Figure 6-17 Filter query 

When we run this query, we get the results shown in Figure 6-18. 



Resources 


0? - = E 

testl 


(2 

a & Resource Type (ID) (1) 



® & Resource Type (PROGRAM) (1) 



Figure 6-18 Results of Testl 
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6.10.2 Modifying an existing query 


You can modify existing queries whether they are supplied predefined queries or 
queries that you created. 

To modify an existing query: 

1 . Right-click the query that you want to edit, and click Edit, or click the query 
that you want to edit, and click Edit ->• Edit Query. The Edit Query window is 
displayed, as shown in Figure 6-19. 



Figure 6-19 Edit query 


2. Edit any aspect of the query that you want. To save the edited query as a new 
query, change the name. Figure 6-20 on page 161 shows the Edit CICS query 
window. 
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Figure 6-20 Edit CICS query window 

3. Click OK to save the query. The query is saved in the same folder that the 
original query is saved. 

6.10.3 Saving your queries in folders 

When you create and define your queries, you can save them in the Queries 
window for future use. 

To save your queries: 

1 . Before you create a query, in the Queries window, click the folder name under 
which you want the query to be listed. You cannot move a query after it is 
saved. 

2. After you name and define your query, click OK, and the query is saved in the 
query folder that you selected. 

3. To delete a query, in the Queries window, right-click the query name, and click 

Delete. 
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6.10.4 Creating a query folder 


You can save queries and query results in the existing folders or create a new 
folder. 

You can create folders under any of the existing folders as a subfolder. To create 
a folder: 

1 . In the Queries window, click the position where you want the folder to be 
created, and select File -» New ->• New Folder, or right-click, and select 
New ->• New Folder, as shown in Figure 6-21 . A folder called New Folder is 
created in the Queries window. 



2. Change the name New Folder to the required folder name. 

3. To delete a query folder, in the Queries window, right-click the query folder 
name, and click Delete. You cannot move an existing folder in the structure. 


6.11 Analyzing query and search results 

You can further analyze the results of any query or search that are displayed in 
the CICS IA plug-in windows. You can view the programs and transactions that 
are used as a resource and the region in which they are using that resource. You 
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have the option to analyze the resource in the region in which it is being used. 
You can analyze the use of each resource across all regions or specific regions. 

To further analyze any query or search results: 

1 . Right-click any resource that is displayed in any window in the CICS IA 
plug-in. 

2. Click Used By or Uses Resources, as shown in Figure 6-22. Only programs 
and transactions have the Uses Resources option. 


L=l Resources 


All programs using files 

(4) 

+ jno PROGRAM (EMSTESTS) (1) 

* 


Used By Programs ► 


Used By Transactions ► 


Uses Resources ► 



Figure 6-22 Used By and Uses Resources options 


3. Click All Regions or a specific region that is shown in the menu: 

- The results for the Used By option are displayed in the Used By window. 

- The results for the Uses Resources option are displayed in the Uses 
windows. 

4. Repeat steps 1 to 3 to further analyze the results in the Used By and the Uses 
windows. 

If you select a resource in the Uses window, the lower panel in the Uses 
window shows the names of the programs that are using that resource. You 
can navigate the program tree that is displayed in the lower panel by using the 
yellow up and down arrows, which move between each resource in order. 

5. To recall previous search results in your current CICS IA plug-in session, use 
the yellow back and forward arrows. The resource currently being analyzed is 
displayed at the top of the window, as shown in Figure 6-23 on page 164. 
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□ Properties »C Used By Q • a B 


Programs using Program(CICREXD) in Region SCSCPAA1 



Figure 6-23 After clicking Used By 


6.12 Comparing query and search results 

When you have a number of query or toolbar search results, you might want to 
compare two or more results. You can select any number of results in the history 
using the Compare search results window. You can also compare saved query 
results. 

The Compare search results window relies on complete searches being of the 
same structure. For large amounts of data, it is more efficient to create a query. 
You can compare query and search results using the Compare search results 
window, which is shown in Figure 6-24 on page 165: 

1 . Click the compare torch icon to open the Compare search results window, 
shown in Figure 6-24 on page 165. Both panels contain a list of all query 
results. Select the results in the left panel to Show resources in those results 
and compare with the results that you select in the right panel to show 
resources that are not in those results. 
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Figure 6-24 Compare search results 


If you want to compare saved query results, you must view the saved query 
results in the Resources window so that the Compare window can include the 
saved query results in your selection of choices. 

2. Click the boxes next to the results that you want to compare. 

3. Click OK. The Resources window displays the results. The comparison that 
was run is identified in the grey section of the Resources window. If there are 
no results, the comparison information is shown but the results window is 
empty. 

4. Optional step: To clear the history of query results from the Compare search 
results dialog box, click the down arrow next to the torch icon to display the 
menu items. Click Clear History. 
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CICS Explorer CM plug-in 
familiarization 


In this chapter, we discuss the CICS Explorer CM plug-in. 
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7.1 CICS CM plug-in overview 

CICS Configuration Manager (CM) provides a single point-of-control for editing, 
reporting, and migrating CICS resource definitions across an enterprise. CICS 
CM is a CICS application that can read from and write to a CICS system 
definition (CSD) file and CICSPlex SM contexts. 

The CICS CM plug-in provides an Eclipse-based infrastructure to view and 
manage CICS CM resource definitions across an enterprise. It supports a subset 
of the function that is available in CICS CM. 

CICS CM introduces the concept of a configuration that can be backed by either 
a CSD file or a CICSPlex SM context, which means that the question of how a 
resource is stored is removed from you because CICS CM provides a single 
experience regardless of whether you are dealing with a CSD or a CICSPlex SM 
context. 

Configurations contain lists, which contain groups, which contain resources. 
Using CICS CM you can manage these resources using create, read, update, 
and delete operations. 

Using the powerful search facility that CICS CM provides you can search for 
resources with common criteria across one or many configurations. 

CICS CM records operations on resources and journals. This information is then 
available as part of the history of a resource and is also searchable on a 
configuration and a group level. 

CICS CM also provides some clean up operations to identify potentially 
redundant resources and those resources that cannot be properly used. 

7.1.1 Setting up the CICS CM plug-in 

When you install the CICS CM plug-in, you must define a connection to CICS 
CM: 

1 . Open the preference page, and select the Connections option. 

2. In the connections pane, select the CICS Configuration Manager option 
from the Type pull-down list, as shown in Figure 7-1 on page 169. 
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Figure 7-1 Connections pane 

When you start using your CICS CM Connection, all of your administration of 
CICS definitional resources occurs through CM and as a result is recorded in the 
journal. 

You might also want to manage operational resources, which you can do by 
associating a CMCI or a WUI server connection with your CICS CM Connection, 
as shown in Figure 7-2 on page 170. 
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Figure 7-2 Manage operational resources 


Now you can view operational resources from your region/WUI and definitional 
resources from CM. You can also install CICSPlex SM Context resources to be 
installed, added, and removed from groups. 


7.2 CM perspective overview 

Installing CICS CM, Figure 7-3 on page 171 , provides a new perspective to the 
CICS Explorer workspace. 
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Figure 7-3 CICS CM perspective 


Within this configuration there are views for configurations, lists, groups, History, 
Search, and some SM Administration views. 

You can customize this perspective like you can with any other plug-in. Your 
changes are saved when you exit the Explorer. 

You might want to open or close any of the views. You can find a particular view 
through the Operations, Administration, or Window -» show view routes. 
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7.3 Configurations view 


The Configurations view displays all CICS CM Configurations: both those 
representing CSDs and those representing CICSPlex SM Contexts. Figure 7-4 
shows configurations. 



Figure 7-4 Configurations 

The configuration information is retrieved from the server when you connect to 
CICS CM and is displayed in an alphabetic table by configuration name. The 
table also contains details of the CSD or Context that the configuration 
represents. 

The different types of configuration are denoted by several icons. 

You can filter the table of configurations by configuration name using the filter box 
at the top of the view. This box includes an implicit wildcard, so, for example, 
searches for C returns all configurations with a name beginning with C. You can 
also use the asterisk (*) to match any number of wildcard characters and the plus 
sign (+) to match exactly one wildcard character. You must press Enter to apply 
your filter. 

You can refresh the configurations view using the Refresh button, which forces 
the view to retrieve the information from the server again. 

Select a configuration in the table to populate the Lists and Groups Views and 
also display information about the selected configuration in the Properties View. 
If you select more than one configuration, only the selection that is closest to the 
top of the table is used to populate these views. 
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Select and right-click one or more configurations to display a context menu with 
several options for searching and clean up operations. We discuss this further in 
later sections. 


7.4 Lists view 

The Lists View, Figure 7-5, displays all lists in the currently selected 
configuration. The configuration information is displayed alphabetically, in the text 
in the top of the view. 



For a configuration that represents a CSD, lists represent the Group Lists in the 
configuration. 

For a configuration that represents a CICSPlex SM Context, lists represent the 
ResDescs in the configuration. 

You can prevent the lists view from changing its content by turning the Link to 
Selection option off. As a result, the view will no longer change contents when 
you select a configuration. You can turn this functionality back on by turning the 
Link to Selection option back on, as shown in Figure 7-6 on page 174. 
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You can filter the lists by name using the filter box at the top of the view. This box 
includes an implicit wildcard, for example, a search for C returns all lists with a 
name that begins with C. You can also use the asterisk (*) to match any number 
of wildcard characters and the plus sign (+) to match exactly one wildcard 
character. You must press Enter to apply your filter. 

You can refresh the Lists View using the Refresh button, which forces the view to 
retrieve the information from the server again. 

Selecting a List populates the Groups View and also displays information about 
the selected list in the Properties View. 


7.5 Groups view 

The Groups view, Figure 7-7 on page 175, displays all Groups in either the 
currently selected configuration or the currently selected list. The last selection of 
either of these types is used to populate the view. This information is displayed in 
an alphabetic list. The information about where the view is being populated from 
is in text at the top of the view. 
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Figure 7-7 Groups view 

For a configuration that represents a CSD, groups represent the csdgroups. 

For a configuration that represents a CICSPlex SM Context, groups represent 
the ResGroups. 

You can prevent the lists view from changing its content by toggling the Link to 
Selection button to the off position. The view will no longer change its contents 
when you select a configuration. You can easily turn this functionality back on by 
toggling the Link to Selection button to the on position. 

You can filter the Lists by name using the filter box at the top of the view. This box 
includes an implicit wildcard, for example, a search for C returns all lists with a 
name beginning with C. You can also use the asterisk (*) to match any number of 
wildcard characters and the plus sign (+) to match exactly one wildcard 
character. You must press Enter to apply your filter. 
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You can refresh the groups view using the Refresh button, which forces the view 
to retrieve the information from the server again. 

Selecting a group in the list populates any open definitional views with the 
resource definitions that are contained in the selected group. 

Selecting a group also displays information about the selected group in the 
Properties View. If you select more than one group, only the selection that is 
closest to the top of the list is used to populate these views. 

Selecting and right-clicking one or more groups displays a context menu with 
several options for searching and creating new definitions. See later sections for 
more information. 


7.6 Definitional views 


By default, in the CM Perspective, shown in Figure 7-8, the following definitional 
views are already open: Transaction Definitions, Program Definitions, File 
Definitions, and TD Queue Definitions. You can customize the perspective in any 
way that you want, including closing these views and opening others. Other 
definitional views can be found through the Administration menu. 



Figure 7-8 CM Perspective 


CICS CM populates these views when a group is selected and all resources for 
the group are retrieved from the server. 

You can manipulate these views by changing the order of columns, configuring 
which columns to display, and applying various filters. 

More detailed information about how to manipulate views is in Chapter 1 , “CICS 
Explorer introduction” on page 3. 
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7.7 Creating, editing, and deleting a resource definition 


In this section, we discuss how to create, edit, and delete a resource definition. 

7.7.1 Creating resources 

CICS CM uses the Creation Wizards that are provided in the Base CICS Explorer 
to enable creation of resources. There are a number of different routes that you 
can take to create a resource definition. 

To create a resource definition: 

1 . From a Group, in the context menu, select New. 

2. From the list, select a specific type or Other, which displays more resource 
types. Select one of these resource types to create a definition of that type. 
Figure 7-9 shows the creation of a bundle definition. 



Figure 7-9 Resource creation 
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3. From a definitional view, locate the context menu, and select New. The 
creation wizard for that type is displayed. Figure 7-10 is an example of 
creating a TD Queue. 



Figure 7-10 New TD queue 

Each type of resource definition displays a different creation wizard because 
each type has different basic attributes that must be entered. For details about 
the creation wizards, see Chapter 1 , “CICS Explorer introduction” on page 3. 

When a definition is created it is then displayed in an editor where further editing 
can occur. 

7.7.2 Editing a resource 

You can use CICS CM to edit your resource definitions in configurations that are 
backed by both CSDs and CICSPlex SM Contexts. 


178 IBM CICS Explorer 


Editors 

CICS CM uses the editors that are provided in the Base CICS Explorer to display 
resource definitions, as shown in Figure 7-1 1 . The same framework is used to 
display and edit resource definitions; however, any changes that you make go 
through the CM server, which ensures that journaling takes place. 



Figure 7-11 Transaction definition 

To open editors on a particular resource definition select the Open option from 
the context menu or double-click the resource. The Editors provide some 
attribute validation, undo capabilities, and context help. Refer to Chapter 1 , 
“CICS Explorer introduction” on page 3 for further information about the Editors 
and how to get the most out of them. 

7.7.3 Deleting a resource 

To delete a resource definition, select the resource, and from the context menu, 
click Delete. 
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7.7.4 Installing a resource 


It is possible to install resources from a CICSPlex SM Configuration into one or 
more active CICS systems, if you also defined an operational connection to work 
alongside the CICS CM connection. 

If the operational connection is defined, the Install option is enabled in the 
context menu for these resources. See 3.1 , “Installing CICS Explorer” on page 46 
for instructions about installing the CICS Explorer. 


7.8 Adding and removing from groups 

You can add and remove resources from groups within a CICSPlex SM 
Configuration, if you also defined an operational connection to work alongside 
the CICS CM connection. 

If the operational connection is defined, the Add to Group option is enabled in 
the context menu for these resources. The Remove from Group option is only 
enabled if the resource definition already belongs to a group. 

See section Chapter 4, “CICS Explorer base familiarization” on page 77 for 
details about adding and removing from groups. 


7.9 History 

In this section, we discuss History. You can review what changed. 


7.9.1 CICS CM journal 

In its journal, CICS CM records information about changes that are made to 
definitions. To keep track of these changes, you must make the changes using 
CICS CM. If you bypass CICS CM using CEDA, the CICSPlex SM WUI, or a 
CMCI Explorer connection, your changes are not recorded in the journal. 

If you use the CICS CM plug-in within the CICS Explorer to make changes to 
definitions through a connection to CICS CM, these changes are recorded in the 
journal. This connection can still be used in conjunction with a CMCI or a 
CICSPlex SM Data Interface connection for operational resources. 
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7.9.2 History View 


The History View displays changes that are made to definitions, as shown in 
Figure 7-12. This view is populated by the current selected definition, group, or 
configuration. 

When a resource definition is selected the History View displays all changes for 
that definition, within the scope of the group that the definition is in. 



Figure 7-12 History view 


When a group or a configuration is selected the History View displays all 
changes within that group or configuration for the last three months. This is a 
default value that you can alter through the Date Range dialog. 

You can prevent the lists view from changing its content by toggling the Link to 
Selection button to the off position. The view will no longer change its contents 
when you select a configuration. You can turn this functionality back on by 
toggling the Link to Selection button to the on position. 

The History View displays information in a table. Each entry in the table 
represents a change made. Maximizing an entry shows the details of which 
attributes were changed: their before and after values. Table 7-1 on page 182 
provides details about the History View. 
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Table 7-1 History view 


Field 

Description 

Revision Time 

Shows the date and time of changes made to the 
resource definition. You can click a date entry in 
this column to display the change properties in the 
Properties View. 

Resource 

Name/After 

When the row is collapsed the only the resource 
name is displayed. If you click the plus sign to 
expand the row, the value of the resource 
attributes after the change is displayed. 

Resource 

Type/Before 

When the row is collapsed the resource type only 
is displayed. If you click the plus sign to expand the 
row, the value of the resource attributes before the 
change is displayed. 

Group 

Shows the group name. 

User Name 

Shows the user who made the change and the 
change that was made to the data. 

Command 

Shows the command that was used to make the 
change, for example, Rename, Update, Delete. 

Change 

Package 

Shows the change package that was used to make 
the change. 

Scheme 

Shows each entry in the journal for the selected 
objects. 


The data in the table is initially arranged by Revision Time; however, clicking any 
of the column headers sorts the data by that column. 

Use the Group By Date toolbar button to turn on and off showing the entries 
group into date categories: Today, This week, Older than this week, Older than 
this month, Older than this year, as shown in Figure 7-13 on page 183. 
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Figure 7-13 Group by date 


You can filter the entries in the History View by selecting one or more filters from 
the view menu. The available filters are: 

► Name 

► Type 

► Group 

► User ID 

► Command 

► Change Package ID 

► Scheme 

Selecting one of these filters creates an input field in the History View. You can 
then enter in a filter value, select is, is not, equals, or apply. Figure 7-14 shows 
the filters. 
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The History View might contain many entries. If you know that you are only 
interested in entries within a specific set of dates, you can filter the view by date 
range. You can change the date range through the Set Date Range dialog, which 
is also available from the View menu, as shown in Figure 7-15. 



Figure 7-15 Set Date Range 

You can restore some changes in the History View, and this options is displayed 
in the context menu of an entry in the History View. The resource definition is 
restored to the values before the change that you selected, as shown in the 
Resource Type/Before column. 

If you restore an entry that was deleted, the resource definition is recreated. If 
you restore a create entry, the resource definition values are restored to the 
values when the resource definition was first created. 

The restore option is not currently available for rename, add, or remove entries. 

You can open a particular entry in the table in an editor, which displays the after 
attributes of the entry in the editor for the particular type and is in read-only 
mode. 

To search for the current version of a resource definition, select an entry in the 
History View, and then select the Find Current Version. 
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Use the Refresh button to refresh the History View, which forces the view to 
retrieve the information from the server again. 


7.10 Searches and the search view 

CICS CM provides a number of different ways to search for resource definitions. 

CICS CM provides some specific searches and a completely customizable 
search through the search dialog. Search results are displayed in the Search 
Results View. 

Searches can be run against one or more groups within a particular 
configuration. They can also be run against one or more configurations in the 
current CM connection. 


7.10.1 Specific searches 

For any group or configuration you can run the Show All Resources search, 
which you can also run on more than one group or configuration. Simply select 
one or more of either groups or configurations, and select Show All Resources. 

On any resource definition certain specific search options are displayed under 
the Find context menu. All resource types have an option to search for Similar 
resources. This feature searches for all resource definitions that have the same 
name and type as the resource definition that is selected, within in the same 
configuration. 

Program Definitions have an additional specific search option. You can search for 
transactions that reference the selected Program. 

LSR Pool Definitions have an additional option. You can search for files that 
reference the selected LSR Pool. 

7.10.2 Using the search dialog 

Using the search dialog you can perform more powerful searches to be run with 
filter criteria. 

The search dialog is available from the Search icon in the toolbar or from the 
context menu when you select a configuration or a group. 

Figure 7-16 on page 186 shows the Search Definitions. 
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Figure 7-16 Search Definitions 


You can filter by resource name and resource type. You can also select which 
configurations you want to search and (if appropriate) which groups to search 
within a configuration. 

You must enter a resource name; however, you can use wildcards (*) to match 
any name or any number of characters within a string and (+) to match exactly 
one character. 

Further filtering is enabled only when you select a specific resource type, as 
shown in Figure 7-17 on page 187. After which you can select filters from the 
filter pull-down menu, which allows filtering on every attribute for this type. After 
you select a filter, you must enter a value and where appropriate choose 
operators. Filters are joined together in an and clause. 
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Figure 7-17 Additional filtering 

Configurations might be pre-populated if you selected them when the search 
dialog was opened. You can add or remove Configurations from the search 
scope by editing the list that displays when you click the Choose button in the 
Configurations area. 
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Figure 7-18 Configurations area 


Groups might also be pre-populated if any were selected when the search dialog 
was opened. You can add or remove any groups from the search scope by 
editing the list that is displayed when you click the Choose button in the Groups 
area. You can only specify groups within the same configuration. If a group is 
specified, you can only select one configuration. If more than one configuration is 
chosen, groups default to wildcard all groups (*), and the option to choose 
group(s) is disabled. This option is only re-enabled when exactly one 
configuration is selected. 


7.10.3 Search results view 

The search results view displays the results of any searches, as shown in 
Figure 7-19 on page 189. 
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Figure 7-19 Results of searches 


The displayed resources are organized in tree form. If more than one 
configuration is selected, the top level element is a configuration. If all resource 
types are searched, by default results are grouped by type. Definitions that 
appear in more than one group are shown together. 

You can introduce a new layer into the tree, separating the results into their 
resource groups by toggling the Show Groups icon. 

You can navigate to the results of previously run searches through the Show 
Previous Searches toolbar menu within the Search results view. 

Any definitions that appear in the search results view can be further manipulated 
by being deleted, opened, or edited. Any actions you can perform on the 
resource definition when navigated to in a specific resource definition view can 
also be performed from the search results view. 


7.11 Cleaning up 


CICS CM provides some options to help in resource definition clean up. For 
every configuration the options in Table 7-2 are available. 

Table 7-2 Resource definition cleanup options 


Show Resources With Unique 

Shows all resources within the selected configuration 

Names 

that have a unique name. 
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Show Duplicate Resources By 
Name and Type 

Shows all resources within the selected configuration 
that are potentially duplicates, based on name and 
type. 

Show Orphaned Groups 

Shows all groups within a configuration that do not 
belong to a list. 


For CICSPlex SM-based configurations, the additional options in Table 7-3 are 
also available. 


Table 7-3 CICSPlex SM additional options 


Show Shared Resources 

Shows resource definitions that are associated with two 
or more groups. 

Show Orphaned Resources 

Shows resource definitions that are not associated with 
any group. You cannot edit these definitions. 


The results of these queries are displayed in the search results view. 

Properties view 

CICS CM populates the Properties view with the current selection. For resource 
definitions, the Properties view displays the attributes for the definition. 

For Configurations, Lists, and Groups the Properties view displays additional 
information. 
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CICS Explorer PA plug-in 
familiarization 


In this chapter, we discuss CICS PA, mainly focusing on the CICS Explorer 
plug-in for CICS PA. 


© Copyright IBM Corp. 2010. All rights reserved. 




8.1 Overview of CICS PA 


In this section, we provide an overview of CICS PA. 


8.1.1 Runtime product 

The mainframe product provides system analysts assistance in a wide range of 
performance-related measurement scenarios with particular focus on: 

► System performance analysis 

► System tuning 

► Capacity planning 

The runtime product benefits CICS architects, developers, system managers, 
and administrators. 


8.1.2 The plug-in 

The CICS PA plug-in differs from the other CICS Explorer plug-ins because it 
does not utilize a published API on the host; instead, it uses data extracts from 
the PA runtime, from these data extracts targeted reports and analysis can be 
made. 

Analysts can visualize their transaction performance data more easily using the 
graphing and tree views so that they can navigate and identify issues, such as 
Threadsafe, more readily and with less experience and skill. 

At the time of writing, the CICS PA plug-in takes advantage of a subset of the 
main CICS PA runtime reporting functionality, presenting transaction 
performance summary data to you in a more understandable and intuitive way. 

You can access performance data summaries and reporting scenarios through 
CSV files or database (DB2). 

Information is extracted from the CICS PA runtime by a number of routes and can 
be saved either as CSV data or using a database. The data represents various 
measurements that are summarized over a defined time period.The CSV file is a 
simple portable form of data and is ideal when focused at a very specific data 
volume level. The database strategy is preferred for the analysis of larger data 
volumes not only because it can contain so much more historical data, but the 
performance is better from an application point-of-view rather than handling large 
CSV files in memory. 
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Presenting performance data in the context of CICS Explorer allows integration 
with the base explorer and other tools which compliments the historical 
performance information by presenting it alongside see the live data and 
definitions. 


8.2 The PA Explorer environment 

The Eclipse views that the CICS PA plug-in provides, Figure 8-1 , can be used in 
a number of perspectives including the standard Eclipse resource perspective. 



Most users' first point of contact is the Project Explorer view in the top left of 
Figure 8-1 . The Project Explorer is a standard Eclipse view presenting resources 
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such as files and folders to a user. In the context of the PA plug-in, files, such as 
a CSV file extracted from the PA runtime, are contained within a project and 
folders. There are numerous ways to import these files into the explorer, 
including Drag-and-Drop, Copy-and-Paste, plus Import. Consult the online help 
for more detail. 

A similar mechanism to the CSV files is used for database references, which 
allows a consistent interface. The specification and configuration of database 
connectivity is described elsewhere. 

The data that is contained through the CSV or database link is broken down by 
date, time, Applid, and transaction. This type of taxonomy makes it easy to 
navigate to a specific point of time to find a particular area of focus. Figure 8-2 
shows data exposed using the CSV. 


1 sampllvcsv 

a# 2»; 


-2008 

l 03:30:00.000 
03:50:00.000 
3-® A6POC3C1 
! ™V* KD4C (1) 


Figure 8-2 Data using CSV 


After you identify an area of interest, you can see more information by opening a 
Sheet View or one of a series of charts, as shown in Figure 8-3 on page 1 95. 
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Figure 8-3 Bar chart with overlay 


To accompany the main views, you can choose to complement your data picture 
by showing a taxonomy or outline view. This is a sort of a "where am I?" aid. This 
view is only enabled with a CSV file because the database equivalent can be 
immense and adversely affect performance. 

You can also use the standard Eclipse Properties View, which shows every detail 
being held about a transaction instance. Data is organized based upon 
categorizations, which describe later. 


8.3 PA views and editors in detail 

In this section, we discuss the PA views and editors. 


8.3.1 The Project Explorer 

The Project Explorer, Figure 8-4 on page 196, is a standard Eclipse component 
within the Resource perspective, which is also standard Eclipse. When the PA 
plug-in is installed the Project Explorer displays conventional projects, folders, 
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and files, but if these files end with a suffix of CSV or CPA further information can 
be obtained from them, providing that they were created on the PA runtime. 

Because we are using summary data with a unique key we can drill into these 
files and obtain a useful date, time, and applid transaction name taxonomy. 


Note: Project Explorer can also be used to view and manipulate IA queries 
and bundles. 



Contextual menus, Figure 8-5 on page 197, are available on the project explorer 
view depending upon whether you selected one or more of the following options: 


► Date 

► Time 

► Applid 

► Transaction name 
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Figure 8-5 Contextual menu 


8.3.2 The Sheet View 

The Sheet View provides access to the raw detail information that is available 
from a summary report. The data is keyed based upon Start date, Time, the 
Applid, and Transaction name, which uniquely identifies a record instance. 

Those four fields are essential for the PA Explorer to be able to read the CSV or 
database provided data. If these fields are not present, the application will not 
provide any functionality over simply displaying raw data. 

You can choose the columns that are extracted from the PA runtime, but following 
the four columns that form the unique record key is the task termination count 
column. Although not part of the primary key, this value is always required in 
reports as additional information. Omission of this column limits further 
functionality. 

The subsequent columns are as defined by the data extraction process on the 
server. 

Using standard Eclipse functionality you can sort the retrieved columns and the 
columns can themselves be moved so that associated data can be placed side 
by side for visual comparison. However, remember that the sort function, 
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Figure 8-6, only sorts what was retrieved and does not cause a subsequent fetch 
of data to be executed. 



Figure 8-6 Sort function 


Other standard Eclipse functionality includes the ability to copy the data in an 
individual cell to the clipboard to be pasted into a document. Figure 8-7 is an 
example of how to copy data. 



Figure 8-7 Copy data 


You can also select and copy complete rows, as shown in Figure 8-8. 



Explorer Edit Window Help 


Jr3 

„ Undo Ctrl+Z 

— Redo Ctrl+Y 



3 winmvs2e.cpa (1331) ti 


££ Cut Ctrl+X 

b 

pecial/winmvs2e . cpa/2007- 


tpplid I Transact!... 

, 

xT&e Ctrl+V 

YCYZC23 CCVW 

& 

2C Delete Delete 

Select All Ctrl+A 

YCYZC23 CCVW 
YCYZC23 CCVW 
YCYZC23 CCVW 
YCYZC23 CCVW 


2007-01-12 10.55.00 IYCYZC23 CCVW 


Figure 8-8 Copy complete rows 
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8.3.3 Pie chart view 


Pie charts are displayed in the Transaction detail view, as shown in Figure 8-9. 

The pie charts contain a detailed breakdown of a single transaction ID in the time 

period selected. To display the Transaction detail view: 

1 . Select a single transaction in the Project Explorer view or a Sheet View. 

2. Right-click the selection, hover over Performance history, and select Detail 
breakdown. The Transaction detail view is displayed. 

3. Click a pie chart to show the details for a specific analysis type. In Figure 8-9, 
the Transaction detail view is shown with the CPU time pie chart selected, 
displaying detailed CPU time information for the selected transaction ID. 


0 Transaction detail for: pRDS S3 

Start date-23-09-2008, StSft tlme-04:05:00.000, 


0 Transaction detail for: 23-09-2008, 04:05:00.000, A6POS3C4, ORDS 





Figure 8-9 Transaction detail view 

The Transaction detail view displays the following information: 

► A view tab that shows the analysis type and the name of the transaction ID. 

► An information bar below the view tab that contains further details about the 
transaction ID. 

► A pie chart for each type of analysis. You can select each analysis by clicking 
the relevant pie chart. 
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The Transaction detail view contains one or more pie charts depending on the 
data selected and categorization enablement, for example, if the Storage 
categorization enablement is not selected, the Storage pie is not displayed. 
Similarly, if there is no file usage data in the selected sample, the File usage pie 
chart is not displayed. 


8.3.4 Bar charts 

A bar chart, Figure 8-10, displays a bar for each transaction that is selected. 
Each bar contains one or more sectors, and each sector represents different 
information depending on the selection type. 

You can access the bar chart through the Performance History Context menu. It 
is identified by a sub-menu that displays the bar graphic, as shown in 
Figure 8-10. 



Figure 8-10 Creating a bar chart 


The charts are described by scenarios, which give a pointer to what type of data 
is of specific interest. Figure 8-10 shows Threadsafe, which means that the fields 
that will be analyzed and displayed are important when considering a Threadsafe 
issue or concern: 

1 . Select two or more transactions or select a higher tree node, such as an 
application ID that contains two or more transactions, either in the Project 
Explorer view or a Sheet View. 

2. Right-click the selection, hover over Performance history, and select the type 
of analysis to perform. 

A new view opens displaying a bar chart for the selected analysis. In Figure 8-1 1 
on page 201 , a storage analysis is selected, and the Storage view is shown with 
a bar chart for each of the selected transaction IDs. 
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The bar chart view displays the following information: 

► A view tab, containing the name of the analysis in this case, Storage. You can 
hover over the tab to show the data source file and number of records in the 
sample. 

► An information bar below the view title, that contains the path and name of the 
data source file that contains the data. 

► Stacked bars that consist of one bar for each transaction ID selected. Each 
bar in a stack consists of one or more sectors, each representing a different 
field. You can hover over a sector to show further information about the field. 

► A Legend icon in the top left corner of the chart. Click this icon to display the 
chart legend. The legend shows only the colors in use in the current chart. 

You can select one or more bars and perform a further analysis on the 
information by right-clicking and selecting a new analysis from the menu. 

8.3.5 Timeline charts 

A timeline chart displays all instances of a transaction ID in the selected 
application ID across either the whole data file or a range of dates specified using 
the Date dialog when selecting the data, for example, selecting the single record 
with a transaction ID of CRTP in an application ID of IYCYZC20 displays a bar for 
every instance of the transaction ID in the application. To display a timeline chart: 

1 . Select a single transaction, either in the Project Explorer view or a Sheet 
View. 

2. Right-click the selection, hover over Performance history, and select the type 
of timeline analysis to perform. The restrict analysis time period dialog is 
displayed, as shown in Figure 8-12 on page 202. 
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Figure 8-12 Restricting analysis time period 


3. Select the time period to restrict the display to show only data between the 
two dates. Click OK. A new view opens displaying a timeline chart. In 
Figure 8-13, an analysis of transaction ID CRTP in application ID IYCYZC20 
is selected. 



The timeline chart displays the following information: 

► A view title that contains the name of the analysis, in this case, Response 
time. You can hover over the tab to show the data source file and number of 
records in the sample. 
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► An information bar below the view title that contains the name of the CSV or 
database file that contains the data, the application ID, and the transaction ID. 

► Stacked bars that consist of one bar for each instance of the selected 
transaction ID in the application ID. Each bar in a stack consists of one or 
more sectors, each representing a different time field. You can hover over a 
sector to show the average time value for the CPU time field. 

► A Legend icon H in the top left corner of the chart. Click this icon to display 
the chart legend. 

You can select one or more bars and perform a further analysis on the 
information by right-clicking and selecting a new analysis from the pop-up menu. 

By using multiple timeline charts you can compare the way transactions are 
performing in one CICS region against the way they perform in another CICS 
region and identify potential problems. Figure 8-14 shows the timelines for the 
same transaction ID over the same period of time but running under different 
applications. 



Figure 8-14 Multiple timeline charts 


For more information about the details in specific timeline charts, see the related 
links at the end of this book. 
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8.3.6 Properties View 


Another Eclipse view. You can select a single transaction ID from the Project 
Explorer view or from a chart, and display all of its properties in the Properties 
View. 

1 . From the workspace menu, click Window ->• Show View Properties. The 
Properties View is displayed. 

2. Select a single transaction in the Project Explorer view, Sheet View, or a chart 
view. 

All of the details for the selected transaction ID are displayed in the Properties 
View, as shown in Figure 8-15. 
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8.3.7 Integrating with other plug-ins 


The CICS Explorer provides contextual menus that are populated based upon 
what type of object is currently selected and what other plug-ins are currently 
loaded. 

A single selection is represented by a row in the Sheet View, a column in a bar 
chart, and a detail view or a single transaction in the Project Explorer, which 
represents a single instance of a summary record and has specific information 
regarding the transaction ID and Applid. Consequently those parameters can be 
used as contextual parameters within the Interdependency Analyzer plug-in or 
the System Management plug-in, as indicated in Figure 8-16. 



Figure 8-16 Contextual menus 


Figure 8-17 shows the dependencies. 



Figure 8-1 7 Dependencies 


8.4 CSV data extraction process 

In this section, we discuss the CSV data extraction process. 
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8.4.1 Server process 


CICS PA provides report forms to enable a CSV data extract to be created using 
the Extract and Export option of the CICS PA Report Sets panel. 

For CICS PA V2.1 users, a new Sample Summary Extract Report Form 
EXPLORE3 is provided by APAR PK71846. 

For CICS PA V3.1 users, a new Sample Summary Extract Report Form 
EXPLORE4 is provided with the product. 

When you create the CSV extract report, make sure that the Extract Format 
delimiter is set to a comma rather than the default semicolon. You can then 
download the CSV file to your workstation to be used within the CICS PA plug-in. 


8.4.2 Plug-in process 

You can load CSV data into the CICS PA plug-in using three ways: 

► Copy and paste 

► Drag and drop 

► The import function of CICS PA plug-in 

Other plug-ins: Using an application other than CICS PA plug-in to make 
changes to the CSV file might cause errors and make the data unusable by 
CICS PA plug-in. 


Locate the performance data file that you want to analyze and follow one of the 
methods below to load the data into the CICS PA plug-in. 

Using copy and paste 

To copy and paste a file into PA Explorer: 

1 . Copy the data file by right-clicking and selecting copy from the menu. 

2. In the Project Explorer view, select the folder where you want to store the 
data. 

3. Right-click, and select Paste from the menu. 

A copy of the data file is now in the CICS PA plug-in and available for analysis. 

For further information about loading data and other Eclipse functions, see the 
Eclipse workspace User Guide. 


206 IBM CICS Explorer 




Using drag and drop 

To drag a file from your file manager and drop it into PA Explorer: 

1 . In your file manager, select the data file. 

2. Use your mouse to drag the file across to the Project Explorer view. 

3. Put the cursor over the folder where you want to store the data file, and 
release the mouse to drop the file into the folder. 

A copy of the data file is now in the CICS PA plug-in and available for analysis. 

Using the Import function 

To import a file into PA Explorer from your local file system using the Eclipse 

import function: 

1 . Right-click anywhere in the white space of the Project Explorer view, and 
select Import. 

2. In the Import dialog box, select File System. To assist in locating the file 
system, you can type File System in the text field. Click Next. 

3. In the Import wizard, enter the directory path of the data, or click Browse, and 
select the directory from the list. All of the files in the directory are displayed in 
the Import wizard. 

4. Select the data file to be imported. 

5. In the Into folder text box, type the name of the folder where the data will be 
stored, or click Browse, and select the target from the list. Click Finish. 

A copy of the data file is now in the CICS PA plug-in and available for analysis. 


8.5 Database extraction process 

In this section, we discuss the database extraction process. 

8.5.1 Server process 

CICS PA also enables SMF data to be loaded into a DB2 table by first loading the 
data into a Historical Database (HDB). From the HDB, you can export the data to 
a DB2 table or to a CSV file to use in the CICS PA plug-in. 

The steps to Load CICS performance data from an SMF file into an HDB and 
exporting the data from an HDB file to a DB2 table or a CSV file are in Chapter 4 
of the User’s Guide for CICS PA Version 3.1 . See IBM CICS Performance Analyzer 
forz/OS User’s Guide Version 3 Release 1, SC34-7046-00 for more details. 
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8.5.2 Plug-in process 


You can analyze CMF performance data that is produced by CICS Performance 

Analyzer for z/OS and stored in a database: 

1 . From the workspace menu bar, click Window ->• Preferences. 

2. Click IBM CICS Performance Analyzer ->• Data sources. The Data sources 
dialog for CICS Performance Analyzer is displayed in the Preferences view. If 
it was pre configured, you see the connection details displayed; otherwise, the 
fields are blank. Figure 8-18 shows the PA Data sources dialog, which 
contains sample connection details to a DB2 database. 



Figure 8-18 CMF performance data 
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3. Click New to create a new connection. 

4. Complete the fields with the details that your system administrator provided. 
Table 8-1 provides a description of the fields. 


Table 8-1 Option description 


Option 

Description 

Name 

The local name that is used to identify this 
database connection. The name can be anything 
you choose and is used only to help you 
distinguish between different database 
connections. 

Preferred 

Denotes the default data connection when 
accessing the plug-in from another plug-in. 

Server 

Address 

The TCP/IP host name of your database server. 

TCP/IP Port 
Number 

The port used to access the server. 

Database 

Name 

The name of the database on the server. 

Schema 

(Qualifier) 

The name of the schema that is used for the 
database. 

Userid 

Your authorized user ID for the database. 

Password 

Your password for the system. If you leave this 
field blank, you are asked to enter your password 
when the connection is attempted. 

Save 

Password 

Clicking this box saves your password on your 
computer. 


5. Click Apply to save the configuration. 


6. Click Test Connection. 

When Test Connection is clicked CICS PA plug-in attempts to connect to the 
database that you configured. If you did not previously enter your password, you 
are asked to enter it now. 

If the connection is successful, a message box opens at the bottom of the Data 
sources dialog showing the status, and you can now select data for analysis. 
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If the connection is not successful, the message box displays an error message 
that provides a reason for the failure. Check the values in the fields, correct any 
errors, and click Connect to test the corrections. 

When the connection is successful, click OK to close the Preferences view. 

If you did not click Apply, you can cancel the process and close the Preferences 
view without saving the new connection, by clicking Cancel. If you already 
clicked Apply, you must click Delete to remove the connection. 

You can use the Data sources preference page to maintain multiple connections, 
which allows you to specify many different databases 

Project Explorer CPA file definitions 

To use the database table in the Resources View you must define the table 
based upon the database connection that you previously defined: 

1 . From the Project Explorer, select either a Project or Folder in which you want 
to create a link file. 

2. Select New -> Other (Shortcut Ctrl-n) to display Figure 8-19 on page 21 1 . 
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Figure 8-19 CPA file definitions 
Figure 8-20 on page 212 shows the data source. 
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Figure 8-20 CICS Data source 


3. Select New CICS Data Source Node, which displays Figure 8-21 on page 213 
with default values populated, where available. 

4. The Data source defaults to the Default Data Context but can be changed to 
another. The filename defaults to the data source with an additional cpa 
extension. The table name defaults to EXPLORER_SUMMARY in 
accordance with the server data extraction requirements. 

5. Press Finish. 

A link to the database table is now in CICS PA plug-in and available for analysis. 

Click the Properties menu option on a cpa file (Alt-Enter shortcut) to access 
methods to alter some of these settings and test that the connection with the 
table works. 
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Figure 8-21 Properties 

Default data context 

It is important to note that when CICS PA plug-in is accessed from another 
plug-in, a default data context is used based upon the Data source that is 
specified as preferred. In addition, the table name must be described as 
EXPLOREFLSUMMARY. 
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9 


CICS Explorer TG plug-in 
familiarization 


In this chapter, we discuss CICS Transaction Gateway (CICS TG), focusing on 
the CICS Explorer plug-in for CICS TG. 
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9.1 CICS Transaction Gateway introduction 


The CICS Transaction Gateway is a set of client and server software components 
that allow a remote client application to invoke services in a CICS region. The 
client application can be either a Java™ application or a non-Java application. 
Depending on the platform, the non-Java application might use either a C (EClvl 
and ECIv2), C++, COBOL, COM, or .NET interface. 

9.1.1 CICS TG products 

The CICS TG is available through the following two products: 

► CICS TG for z/OS 

CICS TG for z/OS V8 is the latest version for the z/OS platform. It is 
supported on z/OS VI R9 and later and supports connectivity to a CICS TS 
for z/OS V3R1 or later release. 

The CICS TG for z/OS provides comprehensive support for two 
phase-commit transactions along with support for SSL connections, high 
availability topologies, and advanced systems monitoring. It uses either the 
external communication interface (EXCI) or the IP Interconnectivity (IPIC) 
protocol to communicate with CICS regions for z/OS. It provides API support 
for Java and non-Java applications making ECI calls to COMMAREA or 
channel- and container-based CICS applications. 

► CICS TG for Multiplatforms 

CICS TG for Multiplatforms V8 is supported on the following range of 
operating systems and platforms and is designed to support connectivity to 
any release of CICS on any platform: 

- Linux on System z 

- Linux on Intel® 

- Linux on POWER® 

- AIX® 

- HP-UX (on PA-RISC and Itanium®) 

- Sun Solaris (on SPARC) 

- Windows XP, Windows 2003 and Windows Vista 


9.1.2 CICS Transaction Gateway components 

In this section, we describe the key components of the CICS TG product. 

Figure 9-1 on page 217 shows the components of CICS TG for Multiplatforms 
product and its positioning in the product architecture. The resource adapters are 
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shipped as part of the CICS TG product for deployment to a WebSphere 
Application Server in support of JCA clients. 



Figure 9-1 Components of CICS TG for multiplatforms 


The CICS TG for z/OS platform, unlike the distributed platforms, does not include 
the Client daemon. The CICS TG on z/OS does not require a Client daemon 
because it communicates with the CICS TS using either the IPIC or EXCI 
functions that CICS TS provides. Figure 9-2 on page 218 shows the components 
of CICS TG on z/OS. 
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Figure 9-2 Components of CICS TG for z/OS 


In this book we use CICS TG for z/OS. 


9.1.3 The Gateway daemon 

The Gateway daemon listens for incoming remote client requests and manages 
the threads and connections necessary to ensure good performance. The 
performance and the features provided by the Gateway daemon running on the 
z/OS platform differ from the Gateway daemon running on distributed platforms. 
The Gateway daemon handles remote client requests using its protocol handlers 
component. The Gateway daemon can be configured to support both TCP/IP 
and SSL protocols. 


9.2 CICS TG plug-in overview 

The CICS TG plug-in provides a Gateway daemon’s view and a CICS 
connection’s view in the CICS TG perspective of the CICS Explorer. You can view 
the status and activity of one or more Gateway daemons running on any platform 
in the Gateway daemons view. Use the CICS connections view to see the 
connectivity between CICS servers and one or more Gateway daemons. 
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When you switch to the CICS TG perspective, you obtain fast access to the new 
views. Each view includes a number of attributes by default. You can add or 
remove attributes as required. You can see the full set of attributes in the 
Properties view. The attributes are grouped into predefined categories. 

The ability to create a composite perspective is a powerful feature of the CICS 
Explorer. You can add the views provided by the CICS TG plug-in for CICS 
Explorer to other perspectives. You can customize the CICS TG perspective to 
add other CICS Explorer views. 

9.2.1 CICS TG Explorer view 

The CICS TG Explorer view, Figure 9-3, displays the CICS Transaction 
Gateways that are being used and the CICS server connections associated with 
the CICS Transaction Gateway. You can test Gateway and CICS connections and 
refresh the status of the CICS Transaction Gateways. 


4K CICS TG Explorer 
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Figure 9-3 The CICS TG Explorer view 


9.2.2 Gateway daemon view 

The Gateway daemons view, Figure 9-4, displays status and activity information 
for Gateway daemons that are both defined and available. The columns in the 
Gateway daemon view can be customized according to needs. 


CNX0211I Context: SC66. Resource: Gateway. 1 records collected at 20-10-2010 13:34: 15 
Name Status Version Gateway® Netname UpTime 1 Health Platform HAExit I Default 

EPREDCTG []► RUNNING 8.0.0.0 SC66.EPREDCTG EPREDCTG 02:57:00 100 z/OS 0 EPRED9 


Figure 9-4 The Gateway daemon view 
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9.2.3 CICS connections view 


The CICS connections view, Figure 9-5, displays status and activity information 
for the defined CICS server connections and active CICS server connections. 
The columns in the view can be customized. 


-tt- aCS connections 

CN X0211 I Context: SC66. Resource: Connection. 1 records collected at 20-10-2010 13:34:09 
Server Gateway Protoco Target Default AllocSess FailSess Applid CommsFa Requests Response 

jEPRED9 EPRBDCTG # EXCI A — — - ■- — 


Figure 9-5 The CICS connection view 


9.2.4 Console view 

The console view displays the output from the test facilities that are available with 
the CICS TG plug-in. 

Testing the Gateway connection 

To test the Gateway connection, right-click the Gateway daemon, and click Test 
Gateway connection, as shown in Figure 9-6. 


B C3 ZT01 

e Q scee 


^ JB Refresh status ^ 

Test Gateway connection 


Figure 9-6 Testing the Gateway connection 

Figure 9-7 shows the result of the test in the Console view. 


B Console SS\ ^ 

Attempting to open connection to Gateway daemon using host wtsc66.itso.ibra.com on port 4.451 
Success: Opened connection to wtsc66.itso.ibm.com on port 4.451 

Figure 9-7 The Console view - testing the Gateway connection 

Testing the CICS TS server connection 

To test the connection to the CICS TS server, right-click the CICS server, and 
click Test CICS connection, as shown in Figure 9-8 on page 221 . 
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Figure 9-8 Testing the CICS connection 

Figure 9-9 shows the result of the test in the Console view. 


!D Console 




Console 




Attempting to open connection to Gateway daemon using ho 
Attempting to run program PONG on CICS server EPRED9 
Success: Time spent in ECI call was: 109 ms 



on port 4.451 


Figure 9-9 Console view - testing the CICS connection 


Attention: Testing the CICS connection requires supportpac CH50 to be 
installed. 


9.3 Configuration 

In this section, we show how to configure the CICS TG daemon and the CICS 
Explorer TG plug-in. 


Note: A basic knowledge of CICS TG is assumed. We explain how to 
configure CICS TG for use with the plug-in, not the CICS TG itself. 


9.3.1 Configuring the CICS TG for the plug-in 

In this section, we discuss how to configure CICS TG for the plug-in. 

Statistics API protocol settings 

We use the parameters shown in Example 9-1 on page 222 to define a statistics 
API protocol handler in the ctg.ini file. 
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Example 9- 1 Enabling the statistics API protocol handler 


protocol Pstatsapi .parameters=connecttimeout=2000;\ 

port=9091;\ 

maxconn=5; 


The valid parameters are: 

Bind address The bind parameter sets the IP address or name of the 

host to which the protocol handler is to be bound. 

Port The port parameter specifies the number of the TCP/IP 

port on which the protocol handler listens for incoming 
client requests. 

Connection timeout The connect timeout parameter specifies how long the 
protocol handler waits in milliseconds for a connection 
manager thread to become available. 

Maximum number of connectionst 

The maxconn parameter specifies the maximum number 
of applications that can be connected at the same time to 
perform statistic queries. 

We see the message in Example 9-2 after the successful start of the CICS TG 

daemon. 

Example 9-2 Daemon message after successful start 

CTG6524I Successfully started handler for the statsapi : protocol on 

port 9091 


9.3.2 Configuring the CICS TG plug-in 

Next, we configure CICS Explorer to connect to the daemon: 

1 . Start the Explorer, and switch to the CICS TG perspective. 

2. Select Window Preferences, and enter the following values, as shown in 
Figure 9-10 on page 223: 


Connection Type 
Connection Name 


CICS TransactionGateway 
Name for this connection 


Location Host name Host name or IP address of the system where the 
CICS TG daemon runs 


Location Port 


Port number as specified in the statistics API protocol 
handler. See Example 9-1 
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Figure 9-10 CICS Explorer TG plug-in connection definition 


3. With all parameters populated, click connect, as shown in Figure 9-1 1 on 
page 224. 
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Figure 9-11 Connect to the Gateway 
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CICS Explorer Tivoli 
OMEGAMON XE plug-in 
familiarization 


In this chapter, we focus on the CICS Explorer OMEGAMON XE plug-in and the 
functionality that it provides. 


© Copyright IBM Corp. 2010. All rights reserved. 
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10.1 Tivoli OMEGAMON XE for CICS Introduction 


Tivoli OMEGAMON XE for CICS provides the ability to proactively monitor basic 
and complex CICS systems. It provides performance and availability information 
that can be leveraged to pinpoint bottlenecks, and avoid downtime. OMEGAMON 
XE provides insight into currently occurring issues, which allows the user to 
choose an informed course of action. 


10.1.1 Tivoli Enterprise Monitoring Server (TEMS) 

The Tivoli Enterprise Monitoring Server (TEMS) gathers data from the Tivoli 
Enterprise Monitoring Agent (TEMA), and acts as a collection and control point, 
for alerts. Data received is sent to Tivoli Enterprise Portal clients, where it can 
then be displayed in tabular or graphic views. Requests for information or action, 
from Tivoli Enterprise Portal clients can be accepted and distributed to the 
agents for processing. 

10.1.2 Tivoli Enterprise Portal Server (TEPS) 

The Tivoli Enterprise Portal (TEP) is a Java-based interface. It provides access 
to the data monitoring and management resources within IBM Tivoli Monitoring. 
The TEP is installed on its own server, which is the Tivoli Enterprise Portal 
Server (TEPS). The server performs common TEP functions that reduce the 
processing that the Tivoli Enterprise Portal client must perform. 


10.2 CICS Explorer Tivoli OMEGAMON XE plug-in 

The plug-in provides the ability to view OMEGAMON data in Eclipse-based 
applications, such as CICS Explorer. 

Most Tivoli monitoring systems, including their status information, can be 
displayed. Monitoring data from Tivoli OMEGAMON XE for CICS and Tivoli 
OMEGAMON for CICS TG can also be accessed. The plug-in can also display a 
list of currently active situations. 


10.2.1 Installation requirements 

Consult the IBM Tivoli Monitoring: Administrators Guide for specifics regarding 
the Tivoli configuration steps. 
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The installation requirements are: 

► TEMS SOAP Interface: The plug-in communicates with the TEMS server 
through the TEMS SOAP Interface: 

- A version 6.1 (or later) TEMS server is required. 

- The TEMS server SOAP Interface must be configured and enabled. 

- Currently the plug-in does not support Secured Socket Layer (SSL) 
connections to the TEMS SOAP Interface. 

- It is important that a fixed TEMS port is assigned as part of the 
configuration. If a fixed port is not set, the port number changes each time 
the TEMS address space is recycled. 

► TEPS Client Files: The plug-in utilizes files shipped with the TEP client. The 
files are not required, but failure to use them results in severely curtailed 
functionality. If you choose to use the TEPS Client Files they must either 
reside on, or be copied to the machine that will run the plug in. 

- The files are named dockpp, where pp is a two character product code. 
Example: dockcp, dockgw, dockn3, and so on. 

- The files can be found on the machine where TEPS is installed: 

• For Windows platforms look in the <ITM DIR>\CNPS directory 

• For other platforms look in the <ITM DIR>/<arch>/cq/data directory 

- The files can also be found on the host z/OS platform, in the RKANDATV 
library. In this instance, you can FTP the files, in ASCII mode (not binary), 
to the machine that will run the plug-in. 

10.2.2 Installing the plug-in 

1 . Go to the CICS Explorer Download Site at: 
www. i bm. com/software/ci cs/expl orer/downl oad 

2. From the Other Downloads section, select the OMEGAMON XE for CICS 
plug-in link. 

3. Select Download, and download the zip file. 

4. Unzip the zip file. The contents include a documentation file with detailed 
installation instructions and another zip file. 

5. Follow the detailed installation instructions in the documentation file to install 
the plug-in. The documentation also covers connection configuration and how 
to access the new IBM Tivoli Monitoring perspective. 
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10.3 Using the plug-in 


When the connection is made to the SOAP sever, information regarding the 
monitored systems is used to construct a navigation tree. 

The IBM Tivoli Monitoring perspective is made up of three panels, as shown in 
Figure 10-1. 



Figure 10-1 Multiple TEMS and Products 


10.3.1 IBM Tivoli Monitoring Navigation Tree display 

Contained in the left panel, this display is similar to the TEP client topology 
display. It performs a function that is similar to the CICS Explorer CICS SM 
perspective topology panel. Clicking an item in the tree controls the scope of the 
resources that are displayed in the query results view. 

Currently the plug-in only supports query information for Tivoli OMEGAMON for 
CICS and Tivoli OMEGAMON for CICS TG resources. 
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This view supports the launching of the TEP browser client. TEP launching is 
available by clicking Launch TEP, which is in the topology view's toolbar or as a 
right-click menu option. 

Expand all and Collapse all actions are also available as toolbar or right-click 
menu options. 

10.3.2 IBM Tivoli Monitoring Data display 

The top-right panel contains query results. This panel displays the results of a 
request for data from the SOAP server. The request is issued by selecting the 
report in the topology tree. 

Some reports are not currently supported by the plug-in. Unsupported reports 
typically require additional parameters that specify the data to be returned. This 
category of reports is usually only available as a link target in Tivoli. 

Enterprise Portal (TEP) client. Most reports on the TEP client topology tree (for 
CICS and CICS TG) are supported by the plug-in. 

Note that some OMEGAMON reports contain a large amount of data. Driving 
these reports might result in a large amount of data being requested from the 
TEMS SOAP interface. 

Currently some data types, used by the IBM Tivoli Monitoring servers are not 
fully supported, by the plug-in. Some values might be displayed without 
appropriate scaling, for example, some fields that must be shown as three 
decimal places are left-shifted three places and shown as integer values 1 ,000 
times larger than their actual value. 

The plug-in supports the exporting of the table data as a Comma Separated 
Values (CSV) file. The CSV file can then be imported into a spreadsheet (or other 
application) for further processing or charting. The export function is driven by 
clicking the appropriate action in the toolbar or as a right-click menu option. 

Figure 10-2 on page 230 shows CICS transaction analysis, Launch TEP, Expand 
all, and Collapse all. 
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Figure 10-2 CICS transaction analysis, Launch TEP, Expand all, and Collapse all 


10.3.3 IBM Tivoli Monitoring Situations display 

Located in the bottom-right panel, displays the current TEMS situation events. 
The view is updated every 30 seconds. 

The data is displayed in a tabular form. Clicking a column header causes the 
table to be sorted by that column's value. Clicking the column header again 
reverses the sort order. 

The active situations can be exported as a CSV file. The export function is driven 
by clicking the appropriate action in the table's toolbar or as a right-click menu 
option. 
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CICS Deployment Assistant 


In this chapter, we provide an introduction to the CICS Deployment Assistant. 
This new, tightly integrated plug-in for the CICS Explorer works together with host 
components to give you a powerful toolkit to manage your CICS deployment and 
to discover your CICS assets. 
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11.1 Introduction to CICS Deployment Assistant 

The CICS Deployment Assistant (CICS DA) is a new tool designed to help you to 
discover, model, visualize, and deploy new and existing CICS regions. With CICS 
DA you can visualize and control all your CICS resources. You can also visualize 
and manage all key relationships from a single point of control. With CICS DA 
you can automate and standardize your CICS environment. 

CICS DA is an interactive control system that allows CICS systems programmers 
to create and maintain a CICS environment easily. CICS DA is a part PC and a 
part mainframe based graphical user interface (GUI). The CICS PC part is 
incorporated into the CICS Explorer as a plug-in. 


1 1 .2 The prerequisites for CICS DA 

In this section, we discuss the components that are required to run CICS DA. 

11.2.1 CICS Explorer 

The CICS DA plug-in must be installed in the CICS Explorer VI .0.1 . 


11.2.2 z/OS host component 

IBM z/OS version 1 .9 or higher is required. If access to the MVS™ system log is 
needed by users of CICS DA, z/OS VI .1 1 is required. JES3 user must have z/OS 
version 1.10 or higher. 

11.2.3 CICS Transaction Server 

CICS/TS version 3.1 or higher is required. Recommended is CICS/TS V4.1 . 
APAR PM 15583 with PTF UK60398 and APAR PM15214 with PTF UK60399 
provide the ability for CICS/TS V4.1 server, to access the System Initialization 
Parameters (SIT) and any overrides with CICS DA. 
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11.3 Installing the CICS DA components 

There are three main steps that are necessary to install the CICS DA: 

1 . Install the CICS DA host component. 

2. Perform the post-installation configuration for CICS. 

3. Download and install the CICS DA plug-in. 

Note: We did the installation according to the instructions in the Release 
Notes for CICS Deployment Assistant, and we recommend that you use the 
release notes as a guide to install the products host component. 

You will find the release notes and the zip file for the CICS DA plug-in on the 
CICS Explorer download page. To download both files: 

1. Enter in your browser ibm.com/cics/explorer/download. 

2. Click Link to Download page, and then logon with your IBM ID. 

3. Select CICS Explorer plug-in for CICS Deployment Assistant VI. 1 or 
CICS Explorer plug-in release notes for download. 

4. Save the compressed file in a temporary directory, and do NOT extract the 
file. The CICS Explorer automatically extracts the contents. 

The download does not include the host components; instead, they must be 
ordered separately. CICS Deployment Assistant for z/OS Version 1 Release 1 
Compid 5655-W4800. 


1 1 .3.1 Installing the CICS DA plug-in into CICS Explorer 

In this section, we describe how to install the CICS DA plug-in: 

1 . Download the CICS DA plug-in zip file from the IBM server. Do NOT extract it. 

2. Start the CICS Explorer (must be CICS Explorer VI. 0.1), and click Help ->• 
Software updates Available Software ->• Add Site. A window opens 
entitled Add Site. There you can enter the location of the zip file. 

3. Click Archive, and select the previously downloaded CICS DA plug-in zip file. 

1 1 .3.2 Establishing a connection to a host 

In this section, we describe how to create a CICS DA type connection: 

1 . Start your CICS Explorer and open the CICS DA perspective. You can open 
the CICS DA perspective if you click the CICS DA icon on the right-upper 
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corner. Alternatively you can navigate through Windows -» Open 
perspective Other. There you can select CICS DA. 

2. If you changed the perspective to CICS DA the first time, you see on the 
right-lower corner (see Figure 11-1) that no CICS DA connection is open. 
Refer to Table 4-1 on page 79 to read more about connection manager status 
icons. 


a - No CICS DA connection 


Figure 11-1 No connection defined 

3. Click the text to open the preference connection window. From there you can 
define your connection. 

Note: First define your credentials, specifying user ID and password. Later 
in the connection definition you can refer to these credentials. 

4. Start by selecting the connection type you want to define. In this case it is a 
CICS Deployment Assistant type of connection. 

5. Press New, and give a name for this connection. Also, specify the host name 
and the port name. Refer to the previously defined credentials (user ID and 
password). 

6. Additionally specify the z/OS system ID, console name, and the CICS DA 
data sets HLQ. 

Note: After the installation of the CICS DA host component, there are 
three data sets cataloged on your z/OS system. The <llq> of this data sets 
are SCPHAUTH, SCPHINST and SCPHLOAD. The CICS DA HLQ means, 
that all qualifiers before <llq> must be specified. See Figure 1 1-3 on 
page 235 for an example. 

7. When the connection is defined, click the red square at the lower right corner 
to connect to the host. A successful connection is indicated by a green circle 
as shown in Figure 11-2. 


© - CICS DA Connection 
Figure 11-2 Connection established 

In Figure 1 1-3 on page 235, you can see how we defined our connection. 
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Figure 1 1 -3 Defining a connection for CICS Deployment Assistant 

The CICS DA connected window is divided into multiple frames. 


Note: If you resized the frames or you closed one, perhaps by accident, 
and you want to reopen or resize it, you can use the Window ->• Reset 
Perspective function at any time. 


In the lower window on the right side you might see the error message shown 
in Figure 1 1-4 on page 236. In this case your z/OS level is not VI. 11 (see 
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prerequisites for browsing the MVS system log in 1 1 .2.2, “z/OS host 
component” on page 232). 



Figure 11-4 Error message when z/OS version is lower than VI. 11 


11.3.3 Connection types 

At this point, we do a brief description into connection types because it is 
important to select the right connection type. Early versions of the CICS Explorer 
were using the CICSPlex SM Data Interface only, which was a kind of read-only 
access. The CICS Management Interface (CMCI) followed soon to connect also 
stand-alone CICS regions that are not part of a CICSPLex. This interface allows 
update access. To connect successfully to the CICS DA host component, a new 
CICS DA type connection is required. Table 11-1 provides an overview of the 
connection types that are currently available. For further information, refer to 4.2, 
“Connections and credentials” on page 78. 


Table 11-1 Connection types 


System 

Connection type 

System z/OS 

System z - FTP 

CICPIex 

CICSPlex SM Data Interface (read-only) 

CICSPlex & 
CICS 

CICS Management Interface (CMCI) 

CICS DA 

CICS Deployment Assistant 


1 1 .4 Creating a new CICS DA project 

The Eclipse platform is project oriented, and the CICS Explorer is based on 
Eclipse. So if you want to start new work, you must have a CICS DA project 
open. A CICS DA project is used as the repository where the system 
configuration data that is collected by CICS DA is saved. This system information 
in the project is known as the model. CICS DA projects are created during the 
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system discovery process. You cannot create a CICS DA project without 
performing a system discovery: 

1 . Select Explorer ->• New Wizards -> CICS Deployment Assistant Project. 

2. Specify a name for your project. Select the connection to use for your 
discovery. By default it is the connection currently in use. 

3. Click Discover MVS Images to let the system start to discover your z/OS 
sysplex. 


1 1 .4.1 Discovering and creating the system model 

When you perform a discovery operation you import the discovered system 
information into your CICS DA project. The system information that is contained 
in the project is known as the system model. When you run discovery, CICS DA 
submits a job through FTP to execute a discovery program. The first thing the 
discovery program does is identify all of the MVS systems in the sysplex. You 
then select the MVS images on which to perform the next stage of the discovery 
process. The discovery program then looks at the regions that are running on 
each selected MVS image and identifies supported releases of CICS and other 
running instances, such as CICSPlex SM CMASes, Web User Interface servers, 
and DB2 and MQ servers, as well as CICS Temporary Storage, Coupling Facility 
Data Tables (CFDT), and Named Counter Server. 


Note: Only active instances are discovered. If a CICS region or another CICS 
asset is not active, it will NOT be discovered. 


The Finish button ends the process, creating a new project. The project is now 
visible in the left upper frame. Expand the folder and, click the plus sign to see 
your CICS assets. 


1 1 .5 Discovering your CICS assets 

In this section, we review some figures to give you an overview of how CICS DA 
discovers CICS assets. 

11.5.1 Discovering CICS regions 

The main CICS asset is a CICS region. CICS DA can discover CICSPlex 
managed and un-managed CICS regions with a few clicks. Figure 1 1-5 on 
page 239 gives you an overview how powerful CICS DA is. 
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To discover CICS regions: 

1 . On the left-upper side window, select CICS Regions -» Managed by 
CICSPlex SM and CICS regions -> Unmanaged. 

2. Double-click the EPRED3 region to bring all the information you see in the 
right-upper window, such as, the CICS versions running in that region (660), 
the MVS system ID (SC66), the name of the CICSPlex (EPRED), and the 
name of the CMAS (EPREDC). You can see issues to stop and start that 
region with a mouse click (see 1 1 .5.6, “Starting and stopping CICS regions” 
on page 246). You can even clone the region from that window (see 1 1 .5.7, 
“Cloning an existing CICS region” on page 248) by simply moving and using 
your mouse. 

You can see some blue hypertext (blue underlined text), for instance, Data set 
name. Others are MVS Image, DB2, WebSphere MQ, CICSPlex, and so on. 
Simply clicking that hypertext gives you more information about that topic. 

If you click Data set name, for example, you can edit your CICS startup JCL. 
You can change it, save it, stop CICS, and re-start CICS to activate your 
changes with a few clicks from one window. No need to switch back to TSO or 
SDSF. 

Figure 1 1-5 on page 239 shows the CICS regions. 
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Figure 1 1-5 Discovering CICS regions 


Let us discuss the two windows on the lower part of Figure 11-5. On the left 
window, you can see jobs in your system. The jobs can be running or they are 
already in the held output queue. 

Look at figure Figure 1 1 -6 on page 240, you can see five jobs in the system with 
jobname EPRED3. The first job (JOB02783) was canceled (notice the 
RC=S222). The following three jobs are in the held output queue for further 
review or processing (print or delete). The last job (JOB03997) is currently 
running, indicated by the small green triangle. A double-click opens the whole 
job. Expanding the plus sign gives you all the available JES data sets (for 
example, the JESMSGL, JESJCL, MSGUSR). Clicking the plus sign is 
comparable to the ? in SDSF just before the job. Clicking a specific data set (for 
example, MSGUSR) opens the CICS TDQ CSMT on the right-upper window, 
where you can investigate specific messages. You get the same functionality by 
clicking the z/OS job tab in the opposite window. 
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The window on the lower-right side shows the MVS syslog (if you are on z/OS 
version 1.11; otherwise, see Figure 1 1 -4 on page 236). When you double-click 
the Syslog Tab, the small window expands to a full window. See Figure 1 1-7 on 
page 241 . Now you can easily go through the syslog using the mouse and the 
scroll bar on the right side. 

Notice, the top of the Window, where you can see which MVS syslog you are 
browsing. This also shows the date and start time of the syslog currently viewed. 
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Figure 11-7 Syslog view full window size 


You can enter z/OS commands by clicking the z/OS command tab. In 
Figure 11-8, we entered the z/OS command d i pi info for demonstration 
purposes. 



Figure 11-8 Enter z/OS commands 
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The results of this command are displayed underneath the command line. 

Figure 11-9 shows that the Console tab is activated. We edited and changed the 
start-up JCL and viewed the confirmation message. Next, we tried to shutdown 
CICS and get the response that the CICS was not up at that time. Finally, we 
started the CICS and got the message that a job has been submitted. No need to 
go back to TSO, or switch to SDSF. This all can be done from a single point of 
control. 



Figure 11-9 The Console view 

1 1 .5.2 Checking the CICS topology 

You can distribute CICS applications and the resources they use between 
interconnected CICS regions. You can group CICS regions into CICS system 
groups and CICSPlexes and distribute regions across the z/OS systems on a 
sysplex. That is your CICS topology. Without CICS DA, it requires several steps 
per CICS, plus inside knowledge of the expected CICS topology to get an 
overview of your CICS topology. With CICS DA, you are almost only a couple of 
clicks away to manage the configuration for ALL CICS systems within the 
CICSplex. 

A CICS topology must be well documented. However, the documentation is 
sometimes neglected and often not up-to-date. With the CICS DA, you can easily 
get an up-to-date picture of your current CICS topology. Make the CICS DA 
project window on the left-upper side of your CICS DA perspective your active 
window. Open the CICSPlexes folder and double-click the CICSplex you want to 
investigate. 

To give you an example on how easy you can get up-to-date topology information 
about your CICSPlex, we added Figure 11-10 on page 243. We opened the 
ALLTORS folder to see which CICS regions are dedicated as Terminal Owning 
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Regions (TOR). Clicking any item gives you further information or the possibility 
to change your topology. 



Figure 11-10 Discover the CICS topology 


The CICSPlex topology frame is divided into four sub-areas: 

► Groups 

► Regions 

► CMASes 

► Wills 

The information provided in each sub-area works like a hyperlink. Double-click 
the EPREDC (MP) in the CMAS area for example, opens the CMAS view where 
you get further information and the ability to dig deeper into your CICS topology. 


11.5.3 Investigating CICS initialization options 

CICS initialization options can be at various places. You must have a SIT table or 
at least a pre-generated table with all of the default initialization values. You can 
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have initialization options specified in the SYSIN data set. You can also specify 
initialization options in the JCL. To check all of these options for all CICS regions 
can be cumbersome and time consuming. Additional expert knowledge is 
necessary, for instance, you must know the location of the SIT source and the 
location for the overrides. 

By contrast, using CICS DA, you can stay on one window and make the 
necessary changes to the initialization options, for example, select a CICS 
region, right-click, and highlight Show SIT Parameters. A new menu is displayed 
which then you can select a CICS initialization option location. In Figure 11-11, 
we show how we selected the CICS initialization options specified in the SYSIN 
data set for CICS region EPRED3. 


i rJ* E : ® :»«►! /f’ fi <8 systemz/os 



Figure 11-11 Investigate the CICS initialization options 
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Note: To access the CICS Transaction Server startup initialization table 
parameters (SIT) and any overrides, you must be on CICS/TS version 4.1 with 
UK60398 and UK60399 applied. 


11.5.4 Viewing CICS-related spool files 

If you work with CICS-related spool files, CICS DA eases the handling of this 
process. There is no need to switch back to another interface anymore. Stay 
within the CICS Explorer environment. 

If you refer back to Figure 11-11 on page 244 you see in the lower-right side the 
MVS syslog. Remember that z/OS 1.11 is mandatory for viewing the syslog; 
otherwise, you will see the error message shown in Figure 1 1-4 on page 236. 
The next tab on the right of System Log is z/OS Job. If you click this tab, you see 
all the spool files for the currently selected region, in this case region EPRED3. 
We selected JESMSGLG, as shown in Figure 11-12 to find the Control is being 
given to CICS message. 



Figure 11-12 Find message Control is being given to CICS in spool file 


In the lower left-side window, you can easily change your selection by clicking the 
job you want to see. Alternatively, you can view spool files in that window by 
clicking the plus sign. 


11.5.5 Working with CICS-related data sets and JCL 

Working with data sets is similar to the spool files. An important thing to mention 
here is, you must change the perspective. But you still stay in the CICS Explorer. 
For demonstration purposes, we show Figure 1 1-13 on page 246. We switched 
back to the CICS SM perspective and opened the Files tab. We selected the file 
STOCK to be closed. 
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Notice in the right-upper corner that the CICS SM perspective is now in the 
foreground and the CICS DA perspective is in the background. 



Figure 11-13 Closing a file from the CICS SM perspective 


11.5.6 Starting and stopping CICS regions 

In this chapter, we demonstrate that you can start and stop your CICS regions 
with CICS DA. Switch to the CICS DA perspective. 

Defining a start policy 

Before you can start a CICS region with CICS DA, you must define a policy to 
CICS DA. If you start your CICS systems as batch jobs, select the Batch Job 
option, and add the fully-qualified name of the PDS or the PDS/E, and append 
the member name in round brackets. See example in Figure 11-14. 


Start Policy 
© Batch Job 

Data set name: CIC5SEM.EPRED.jg.JOBS(EPRED3) ] | Browse... | 

O Started Task 

Start Command: ~| 

^ Start Region ■ Stop Region 

Figure 11-14 Start policy for a batch started CICS system 
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When CICS is started as a started task, select the Started Task option, and add 
the start command in the free area after Start Command. 

Starting a CICS region 

To start a CICS region: 

1 . Click Start Region, which is located after the green triangle. 

2. When you are prompted whether you really want to start this region, reply with 
yes. Notice the confirmation message in the console tab in the lower window. 
It confirms that a job (including job number) was submitted. 

Stopping a CICS region 

To stop a CICS region: 

1 . Click Stop Region, which is located right after the red square. CICS DA 
submits a job and uses the MVS MODIFY command to shutdown the CICS 
region. 

2. CICS DA uses the console name that was specified in the connection 
definition (see Figure 11-3 on page 235). You must define this console in 
CICS; otherwise, you will receive an error in the CICS DA console, as shown 
in Figure 11-15. 

An alternative to this is to allow autoinstall for MVS consoles (SIT option 
AICONS=YES). In the CICS Resource Definition Guide, Chapter 42 
Autoinstall, you find further information about implementing autoinstall for 
MVS consoles. 



Figure 11-15 Error message when console is not defined to CICS 


Note: Only Managed Address Spaces (MAS) and stand-alone CICS regions 
are eligible for CICS DA shutdown. CMASes or WUI servers are NOT allowed 
to be shutdown with CICS DA. 
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Checking region status: Refreshing the window 

On the left-side, upper window, you can see all of your CICS regions. The 
regions that are up and running have a small green triangle. However, this status 
does not change until you refresh this window. You can do a refresh either by 
pressing the PF5 key or by right-clicking and selecting Refresh. 


11.5.7 Cloning an existing CICS region 

If your workload grows and you need an additional CICS system, you can use 
CICS DA to clone a region. The CICS region you want to clone must be a 
CICSPlex SM-managed region and it must be up and running. To clone an 
existing CICS region: 

1 . Double-click the region you want to clone. 

2. Select Clone CICS Region Wizard. When a new window opens, specify all 
essential values, such as new applid, sysid, start policy, as shown in 
Figure 11-16. 



Figure 11-16 Clone a CICS region from EPRED3 to EPRED9 
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3. Click Next. A new dialog window shows all of the CICS-related data sets as 
they currently exist and new data set names. 

4. If you have a shared CSD, click that option to indicate that the CSD name for 
both CICS regions is the same. If the new data set name is greyed out and 
the Share option is selected but also greyed out, then the data set must be 
shared, as shown in Figure 11-17. 



Figure 11-17 New data set names 


5. Click Finish to confirm your choices. CICS DA performs a check to ensure 
that the new data set names and batch job do not already exist. If the check is 
successful, the data sets are allocated and initialized. CICS DA then adds the 
new region to your CICSPlex SM definitions and to the system model. Finally, 
the CICS region editor opens showing details of the CICS region, and a report 
is shown in the Console view. 
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There are some operations in which CICS DA cannot execute, such as defining 
the region to your security policy, connectivity steps, MVS system logger setup, 
and so on. This action must occur before CICS can start. 


Hint: CICS DA provides a User Guide. The User Guide is incorporated into 
the CICS Explorer Help function when the CICS DA plug-in is installed. It is a 
valuable source of documentation and information for how-to questions. 


11.5.8 Adding a CICS to an existing CICSPlex 

Using CICS DA you can install the CICSPlex SM definitions in an unmanaged 
CICS region, and add the region to an existing CICSplex and, optionally, one or 
more of the system groups in the CICSplex. CICS DA can add a CICS region to 
a CICSplex only if the region is started by a batch job. For further information, 
refer to the CICS DA User Guide. Remember that you find the CICS DA User 
Guide in the CICS Explorer Help ->• Help Contents when the CICS DA plug-in is 
installed. 
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WebSphere MQ plug-in 


In this chapter, we provide an overview of the WebSphere MQ plug-in. We 
discuss both the WebSphere MQ Explorer and the WebSphere MQ plug-in for 
CICS Explorer. Additionally, we explain how to integrate WebSphere MQ 
Explorer with CICS Explorer and how to manage MQ resources from this 
interface. 


© Copyright IBM Corp. 2010. All rights reserved. 
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12.1 WebSphere MQ plug-in for CICS Explorer 

The WebSphere MQ plug-in for CICS Explorer provides an integration of the 
WebSphere MQ Explorer into the CICS Explorer. Therefore it is possible to 
operate CICS systems and WebSphere MQ resources from the same desktop 
application, providing benefit if you carry out cross system administration, 
monitoring, and problem determination. 


12.2 The WebSphere MQ Explorer 

The WebSphere MQ Explorer, like the CICS Explorer, is an Eclipse-based 
graphical tool that you can use to explore and configure all WebSphere MQ 
objects and resources. The WebSphere MQ Explorer is included with the 
WebSphere MQ server installation. SupportPac MSOT is also available for 
download, separately from the WebSphere MQ Explorer. Having WebSphere MQ 
Explorer installed on your system is a prerequisite to the CICS Explorer MQ 
plug-in. 


12.3 CICS Explorer WebSphere MQ plug-in 

Although you can use CICS Explorer and WebSphere MQ Explorer 
independently, it shows considerable advantages in using the WebSphere MQ 
plug-in into the CICS Explorer. From a single point of control, you can manage 
your CICS resources and your WebSphere MQ resources. 

12.3.1 Downloading SupportPac CS1Q 

To get the latest version of the SupportPac: 

1. Type ibm.com/cics/explorer into your browser. This directs you to the IBM 
web page. 

2. Select Click here to get CICS Explorer - Free Product Download to start 
the download. On the next page you find the download link for SupportPac 
CS1Q. 

3. Accept the software licence agreement, and then the download will start. 
After the download, do not extract the file at that time. 
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12.3.2 Downloading SupportPac MSOT 

To download SupportPac MSOT: 

1 . To download the SupportPac you must have a IBM registered user ID. If you 
have no such user ID, register yourself on the web page before you start the 
download. When you have resolved the registration, you are ready to 
download the 2 files mst0_eclipse331_windows.zip and 
mst0_explorer701 3_windows.zip. 

2. Type ibm.com/webspheremq/explorer into your browser, and download the 
MSTO SupportPac. Note the installation instructions on that web page. 

3. After the SupportPac is downloaded, navigate to the directory where you 
saved the files, and first unpack the Eclipse .zip file. Double-click Setup.exe, 
and follow the on screen instructions to install Eclipse. 

4. After Eclipse is successfully installed, unpack the MQ Explorer .zip file. 
Double-click Setup.exe, and follow the on screen instructions to install MQ 
Explorer. 


Note: IBM WebSphere Eclipse Platform and IBM WebSphere MQ Explorer 
are installed as real Windows application. If you want to uninstall it, you can 
enter the Windows Control Panel subfolder Add or Remove Programs to 
remove it from your PC. 

The CICS Explorer is installed in a normal folder, which you can remove by 
deleting that folder. 
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12.4 Integrating MQ Explorer with CICS Explorer 

In this section, we describe how to integrate MQ Explorer into CICS Explorer. 

12.4.1 Importing CSQ1 into CICS Explorer 

To install the MQ Explorer integration pack into the CICS Explorer: 

1 . Select the menu option HELP of CICS Explorer, and click Software 
updates. 

2. Select Software Updates -» Available Software ->• Add Site button ->• 
Archive. 

3. Specify the previously downloaded csql .zi p file as the input file name, and 
click Open. 

4. Select the appropriate options, and click Install to install the SupportPac. 

12.4.2 Copying WebSphere MQ Explorer files into CICS Explorer 

You must copy two MQ Explorer files into the CICS Explorer. If you did not 
change the installation path, the files are in: 

C:\Program Fi 1 es\IBM\WebSphere MQ\ecl i pseSDK33\ecl i pse\l i nks 
The two file names are 

► com.ibm.mq.explorer-feature-msOt.link and 

► com. ibm.mq.explorerhelp-feature-msOt. link 

Copy the files into this directory or wherever you installed CICS Explorer: 

C:\Program Fi 1 es\IBM\CICS_Expl orer\l inks 

Remember that you can install CICS Explorer in any folder. 


12.4.3 Restarting CICS Explorer 

The MQ plug-in installation is now finished and ready to use when you restart 
CICS Explorer. 


Note: For detailed installation instructions, read the HTML Document 
CS1Q Release Notes - Readme. This readme file is included in the cslq.zip 
file. 
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12.5 Managing WebSphere MQ resources in CICS 
Explorer 


In this section, we describe how to manage WebSphere MQ resources. 

12.5.1 Starting CICS Explorer and switching to WebSphere MQ 
Explorer perspective 

After you successfully install the WebSphere MQ plug-in into the CICS Explorer 
and restart CICS Explorer, locate the MQ Explorer button, which is in the right 
upper corner, as shown in Figure 12-1. It is now listed under all available 
perspectives. Click the icon to open the WebSphere MQ Explorer perspective. 



Figure 12-1 WebSphere MQ Explorer plug-in button 


12.5.2 Defining and connecting a Queue Manager 

Now you must enter some WebSphere MQ-specific credentials. The basic 
information you must have available is to which queue manager you want to 
connect to and what is the port number. 
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To enter this information: 

1 . Right-click the folder Queue Manager in the left window, titled MQ Explorer 
Navigator. 

2. When the pop-up window appears, select Add Remote Queue Manager, 
enter your queue manager name, and click Next. A window opens, where you 
can specify the host name or the IP address and the Port number and some 
additional information. 

In our example in Figure 12-2, we used the queue manager name MQCR. The 
example host name is wtsc66.itso.ibm.com with a port name of 1415. 



ource OCIC5SM 









Figure 12-2 Enter queue manager name, host address, and port number 


3. Click Finish complete the process. The system automatically connects you to 
the queue manger, as shown in Figure 12-3 on page 257 and Figure 12-4 on 
page 258. 
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Figure 12-4 Left-click the queue manager name to show the details 


12.5.3 Hints and tips 

Be careful when entering the WebSphere MQ credentials. A wrong port number, 
for example, can lead to messages that are not necessarily directly pointing you 
to the correct cause of the problem. 

Figure 12-5 shows the error message that you get when the port number is not 
valid. 



Figure 12-5 Invalid Port number message 
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12.6 Migration issues and versioning 


In this section, we describe how to manage different versions and automatic 
software upgrades. 

12.6.1 Multiple CICS Explorer versions coexisting 

You can have several CICS Explorer versions installed on your system. You can 
have more than one instance of CICS Explorer running simultaneously; however, 
each instance must have its own workspace. If you, nevertheless, start two CICS 
Explorers using the same workspace, you will get the message displayed in 
Figure 12-6. 



Figure 12-6 Workspace is looked at by another CICS Explorer instance (version) 


Note: We strongly recommend that you use different workspaces for each 
CICS Explorer version! 


12.6.2 WebSphere MQ plug-in with new CICS Explorer version 
installed 


Before you start the newly installed CICS Explorer for the first time, we strongly 
recommend that you allocate a new workspace. See 3.3, “Updating the CICS 
Explorer” on page 63. 

After you allocate a new workspace and the CICS Explorer is restarted, re-import 
CSQ1 into the CICS Explorer (see 12.4.1, “Importing CSQ1 into CICS Explorer” 
on page 254), and then copy the WebSphere MQ Explorer files (see 12.4.2, 
“Copying WebSphere MQ Explorer files into CICS Explorer” on page 254). 
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12.6.3 Locating and changing the workspace 


By default CICS Explorer allocates the workspace on Microsoft Windows 
operating system in C:\Documents and Settings\username\ .cicsexplorer. You 
can use any name for additional workspaces. If the workspace does not exist, 
CICS Explorer creates it. To change a workspace: 

1 . Create a shortcut to CICS Explorer as shown in Figure 12-7. 



Figure 12-7 Create a shortcut 


2. Right-click the shortcut, and select Properties. 

3. Append your new workspace to the target, as shown in Figure 12-8 on 
page 261 . In this example, we decided to allocate a workspace in 
c:\CICS_Explorer_V1007\workspace. You must not preallocate this folder 
because CICS Explorer automatically does it. 


Note: A shortcut is mandatory. You cannot provide the -data option from the 
primary cicsexplorer icon. 
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Figure 12-8 Append -data 

An alternative way to provide different workspaces is to start explorer from a 
Microsoft Windows command prompt. 
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13 


CICS Explorer 
troubleshooting 


If a problem occurs with the CICS Explorer, you might be able to resolve it 
yourself. If you cannot resolve the problem yourself, you must gather the 
necessary information or documentation before contacting your IBM Support 
Center. 

In this chapter, we describe some of the most common errors that are 
experienced with the CICS Explorer. Also, we explain where the CICS Explorer 
stores diagnostic data and how this data can be displayed or collected prior to 
calling IBM Support. 
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13.1 Common Explorer connection problems 


Table 13-1 lists some of the known connection problems. Although this is not a 
comprehensive list, these are some of the more common problems. 


Table 13-1 Common connection problems 


CNX Messages 

Description 


CNX0104E 

Connection failed with exception NOTAVAILABLE, 
CPSMAPI 

5.1.1 

CNX0104E 

Connection failed with exception The markup in the 
document preceding the root element must be 
well-formed 

5.1.2 

CNX0104E 

Connection failed with exception The element type 
“HR” must be terminated by the matching end tags 
</HR> 

5.1.3 

CNX0106E 

Connect failed with error Forbidden 

5.1.4 


13.1.1 Connection not available, CPSMAPI 

The CICS Explorer is attempting to connect using the System Management 
Single Server (SMSS) connection. The Explorer fails with the message in 
Figure 13-1 on page 265. 
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^njxj 


Date: 2009-11-2016:36:57.656 


Severity: & Warning 

Message: |CNX01 04E Connection failed with exception NOTAVAILABLE. CPSMAPI 


■ 3*14 


Exception Stack Trace: 

com.ibm.cics.core.comm.ConnectionException: com.ibm.cics.sm.comm.sm.SMConnectionException: NOTAVAILABLE 
atcom.ibm.cics.core.ui.ConnectionManager.connect(ConnectionManager.java:130) 
at com.ibm.cics.core.ui.UIPIugin$1 2,runSub(UIPIugin.java:933) 

atcom.ibm.cics.edipse.common.ui.JobWithCancelingSupport$1.run(JobWithCancelingSupport.java:36) 

atorg.eclipse.core.internal.jobs.Worker.run(Worker.java:55) 

Caused by: com.ibm.cics.sm.comm.sm.SMConnectionException: NOTAVAILABLE, CPSMAPI 

atcom.ibm.cics.sm.comm.sm.internal.SMResponseHandler.getResponse(SMResponseHandler.java:130) 

atcom.ibm.cics.sm.comm.sm.internal.SMCPSMConnection.get(SMCPSMConnection.java:592) 

atcom.ibm.cics.sm.comm.sm.internal.SMCPSMConnection.getResources(SMCPSMConnection.java:916) 

atcom.ibm.cics.sm.comm.sm.internal.SMCPSMConnection.getCMASName(SMCPSMConnection.java:253) 

at com. ibm.dcs.sm.comm.sm. intern al.SMCPSMConnection.conned(SMCPSMConnection.java:243) 

atcom.ibm.dcs.sm.comm.sm.SMConnedion.conned(SMConnedion.java:62) 

at sun.refled.NativeMethodAccessorlmpl.invokeO(Native Method) 

atsun.refled.NativeMethodAccessorlmpl.invoke(NativeMethodAccessorlmpl.java:39) 

atsun.reflect.DelegatingMethodAccessorlmpl.invoke(DelegatingMethodAccessorlmpl.java:37) 

atjava.lang.reflect.Method.invoke(Method.java:599) 

atcom.ibm.cics.core.comm.internal.ConnectionDescriptor$ConnectionlnvocationHandler.invoke(ConnedionDesc 



Session Data: 


|eclipse.buildld=unknown ~*1 

|java.fullversion= J2RE 1 .6.0 IBM J9 2 A Windows XPx86-32 jvmwi3260-2009021 5_29883 (JIT enabled. AOT enabled)^] 



Figure 13-1 CNX0104E Connection failed with exception NOTAVAILABLE, CPSMAPI 


With this error there are a few things you must verify: 

► Is the SMSS active in the CICS region? If you view the JESMSGLG, you will 
want to see the following messages: 

- EYUX0001 1 applid SMSS initialization program starting 

- EYUXL0003I applid CPSM Version 410 SMSS startup in progress 

- EYUXL0022I applid SMSS Phase I initialization complete 

- EYUXL0007I applid SMSS Phase II initialization complete 

- EYUNL0099I applid SMSS SMSS LRT initialization complete 

Also, make sure the TCPIPServices and URIMAP are created and installed. 
You can check MSGUSR in the CICS SMSS region to confirm this. 

► Additionally, make sure SEYUAUTH or SEYULOAD are included in your 
start-up JCL. If it is not, the Explorer will fail with the same CNX0104E error 
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message in Figure 13-1 on page 265. Ensure that SEYULOAD is in DFHRPL, 
and not in the STEPLIB. 


13.1.2 Connection must be well-formed 

The CNX0104E message, Figure 13-2, can have multiple reason why it is 
generated. 



Figure 13-2 CNX0104E Connection failed with exception... element must be well-formed 


The error might be because the CICS Explorer is trying to connect to a CICS 
region with a TCP/IPService port of 9037. The failure occurs because the 
URIMAP, with path /CICSSystemManagement/*, installed does not reference the 
TCP/IPService of port 9037. Figure 13-3 shows that there is a mismatch in the 
TCP/IPSerivce name (EXPLORER and XPLORER). 



Figure 13-3 Mismatch in the TCP/IPService name 
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Another potential reason for this error to occur is because of the CICS-Supplied 
Group DFHWU not being installed. This supplied group contains the resource 
definitions for CICS Management Client Interface (CMCI), and therefore, it is 
essential for it to be installed. Figure 13-4 shows DFHWU is installed in the 
region. 



Figure 13-4 Installed Supplied Group DFHWU 


13.1.3 Connection missing <HR> tag 

When the message in Figure 13-5 on page 268 is displayed, the connection type 
is set for CMCI, but the specified port number that is being used applies to the 
CICSPlex SM Data Interface. Ensure that you are using the correct port number 
for the connection type you are trying to establish. 
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Figure 13-5 CNX0104E Connection failed with exception... </HR> 


Figure 13-6 shows the correct port number for each of the two interfaces. 



13.1.4 Connection error forbidden 

A connection is attempting to be made with the CMCI to a single CICS region; 
however, this region is contained within a CICSPlex environment. The error in 
Figure 13-7 on page 269 is displayed. 
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Figure 13-7 CNX0106E Connect failed with error Forbidden 


Because there are multiple regions within a CICSPlex environment a single 
connection cannot be made to this CICS region. For this connection to be 
successful, you must remove this single CICS region from the CICSPlex 
environment. 

If none of the errors or messages pertain to your problem, or you cannot correct 
your problem, the next step is for you to contact IBM Support to further 
investigate the issue. The remaining sections of this chapter explain where the 
diagnostic data is located and what information/data to collect prior to contacting 
IBM Support. 


13.2 Workspace and logs 

The CICS Explorer uses a folder, known as the workspace, to save all of its 
settings between user sessions and to store a log of its activity, including any 
errors that might occur. 

On Microsoft Windows operating systems, the default CICS Explorer workspace 
is located at: 

C:\Documents and Settings\<username>\ .ci csexpl orer 

On Linux operating systems, the default CICS Explorer workspace is located at: 

/home/<username>/ . ci csexpl orer 
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If you are not using the default settings but are starting the CICS Explorer with 
the -data command line (or shortcut on Microsoft Windows operating systems) 
option to use an alternate workspace location, you probably already know what 
workspace folder you are using. 

The workspace folder contains, among other data, two logs: 

► The Eclipse log is where errors, which are internal to the Eclipse platform that 
the CICS Explorer uses, can be recorded. It is contained in the file: 
<workspace>/. metadata/, log 

This log is accessible from the Ul (See 13.2.4, “Viewing the error log in an 
external application” on page 273). 

► The IBM CICS Explorer’s own set of tracing files: 

<workspace>/. metadata/.cicsexplorer. trace. N N . log 


IBM CICS Explorer’s tracing files: There might be up to 10 files like this 
one with NN=0 for the most recent to NN=9 for the oldest one and up to 1 
MB in size each. 


13.2.1 Capturing trace data 

When the CICS Explorer is running it is constantly recording trace information in 
its trace buffers. If there is an unexpected failure, the CICS Explorer automatically 
writes the trace information out to the error log to help identify the cause of the 
failure. You can force the current information in the trace buffers to be written to 
disk using the Explorer Trace — > Flush menu option. 

The tracing information is written to disk in the set of tracing files 
<workspace>/. metadata/.cicsexplorer. trace. N N . log . 

Because the tracing facility is built using the standard Java logging API, the same 
tracing information can also be sent to a custom Handler, which you can achieve 
by launching the CICS Explorer with a command line (or shortcut on On 
Microsoft Windows operating systems), such as: 
cicsexplorer -vmargs -Djava. util .logging. config.fi le=myfile 

In the example, myfile, is the name of a Java Properties file that is written 
according to the Java logging API. 

The myfile configuration can, for instance, specify additional FileHandlers with 
different formatting or filtering than the default tracing; however, this is likely to 
have a detrimental performance effect if buffering is not adequate. 
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13.2.2 Tracing options 


The default tracing granularity is adequate, but it can be further enhanced: 

1 . Create a text file, and in the same directory where the CICS Explorer 
executable file resides, name it .options. 

2. Inside the text file, add the lines that IBM service requests, as shown in 
Example 13-1. 

Example 13-1 Options text file 

lExample .options file for CICS Explorer 
# 

com. i bm. cics. core. ui /general =true 
com. ibm.cics. core. ui/selection=false 
com .ibm.cics. core . ui /draganddrop=f al se 
com. ibm.cics. core. ui/resources=false 
com. ibm.cics. core. ui/connection=fal se 
com. i bm. ci cs . core. ui /adapters=fal se 
com. i bm. ci cs . core. ui /preferences=fal se 
com. i bm. ci cs . core. ui /decorators=fal se 
com. i bm. ci cs . core. ui /properti es=fal se 
# 

com. ibm. ci cs . core. model /general =true 
com. ibm.cics. core. model /select ion=false 
com. ibm. cics. core. model /resources=fal se 
com. ibm. ci cs . core. model /adapters=fal se 
# 

com. i bm. ci cs . core. ui . edi tors/markWi thCol ors=fal se 
com. ibm. cics. core. ui .editors/control s=fal se 
com. ibm. cics. core. ui .edi tors/bi ndings=fal se 
com. i bm. ci cs . core. ui . edi tors/propertysheet=fal se 
com. ibm. cics. core. ui .edi tors/act ions=fal se 
# 

com. i bm. ci cs .model /attri butes=fal se 
# 

com . i bm . ci cs . sm . comm/general =true 
com.ibm.cics.sm.comm/record=false 
# 

com. ibm.cics.sm. comm. cpsm/general =true 


3. To use the .options file, start the CICSExplorer with the command line option 

-debug. 
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On Microsoft Windows operating systems, instead of using a command prompt 
window, you can append the -debug option to a shortcut created for the CICS 
Explorer executable. 

Another alternative to specifying a command line option, on all the platforms, is to 
edit the cicsexplorer.ini file. 


File backup: Saving a cicseplorer.ini file that contains syntax errors or is 
missing essential options, can cause CICS Explorer to fail to start. Create a 
back up of the file before you edit it. 


13.2.3 The Error Log View 

The Error Log View displays information messages, warnings, and errors that the 
CICS Explorer logs. The underlying log file is where errors that are internal to the 
Eclipse platform that the CICS Explorer uses, can be recorded. It is contained in 
the file: 

<workspace>/. metadata/, log 

The Error Log View is accessed from the Window Show View Error Log 
menu option. 

The Error Log View is provided for information only. Figure 13-8 shows 
information messages and error messages. The error messages are simulated 
for this example because typically the log does not contain errors. If the view 
contains errors, contact your IBM Service representative for advice. 



The CICS Explorer help contains a detailed description of the sorting, filtering, 
and export capabilities of the Error Log View. 
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13.2.4 Viewing the error log in an external application 


You can view the Eclipse log in an external application, such as a text editor or a 
browser. 

1 . From the menu bar, click Help -> About IBM CICS Explorer. The About IBM 
CICS Explorer window is displayed, as shown in Figure 13-9. 



Figure 13-9 About IBM CICS Explorer 

2. Click Configuration Details. The Configuration Details view is displayed, as 
shown in Figure 13-10 on page 274. 
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Figure 13-10 Configuration Details window 

3. Click View Error Log. You are presented with a list of programs that can be 
used to open and display the log. 

4. Select a text editor or browser from the list, and then click OK. 

The Configuration Details is a comprehensive set of information about your CICS 
Explorer installation that can be of great help to IBM Service when an error report 
is submitted. 


274 IBM CICS Explorer 


13.3 Preparing error data for IBM service 

If you have a problem with the CICS Explorer, you might be asked to send the 
error logs and other information to the IBM service representative. The CICS 
Explorer collects all necessary error information in a single-compressed file that 
is ready for sending. 

To prepare error data for IBM service: 

1 . From the workspace menu bar, click Explorer ->• Trace Collect Service 
Data. 

2. In the Save Service data as file dialog, select the location where you want to 
save the compressed file, and click Save. 

The service data is saved as a compressed file. The filename is in the format 
CICSExplorerServiceData-20090701 -08031 1 .zip, where the numbers indicate 
the date and time of the collected data. 

The zip file contains all of the diagnostic information that we described so far: 

► Eclipse log 

► CICS Explorer traces 

► Configuration details 

It also contains the CICS Explorer configuration settings, such as your defined 
connections and the set of columns to display in the resource views. It does NOT 
contain your saved passwords, which are stored encrypted on disk. 

Remember to record the actions that you were performing at the time the failure 
occurred, which assists the IBM service representative if the problem requires 
further analysis. 

13.3.1 Collecting error data when the CICS Explorer is not usable 

If you cannot use the CICS Explorer user interface to collect service data, for 
example, because of a start up failure or because the user interface is 
unresponsive, you can at least create an archive file (for example in zip format on 
Microsoft Windows and in tar format on Linux) of all the traces, logs, and settings. 
This archive file does not include the comprehensive Configuration details that 
are available through the user interface. 

Simply use an archiving utility to collect the directory content of your workspace 
location. 
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You might want to remove the file where the passwords are stored because 
although they are encrypted, they can be recovered: 

<workspace>/.metadata/.plugins/com.ibm.cics.ecl ipse. common/com. ibm.cics 
.core.ui .secure_storage 

If the user interface is up but hanging and unresponsive, creating a Java Thread 
Dump might be useful. 

Creating a Java Thread Dump on Linux: 

1 . Obtain the process ID of the CICS Explorer using any system tool, for 
example, from a shell (command line) enter: 

$ ps -ef | grep cicsexplorer 

2. From a shell, invoke kill -QUIT <process_id>, and a file named 
javacore.YYYYMMDD.<other>.txt is created in the CICS Explorer directory. 

3. Add the file to the archive that contains the workspace data. 

Creating a Java Thread Dump on Windows: 

1 . The CICS Explorer must have been started with the -consolelog parameter, 
which in addition to the graphical Ul window, also opens a shell (command 
line) window only for output. 

2. If a dump was not taken, enter the key combination CTRL-BREAK from that 
command line window to request a dump. 

3. From the console log window, you will see a message that includes the 
location and name of the dump that you send to IBM, for example: 

JVMDUMP010I Java dump written to C:\...\CICS 
Expl orer\j avacore . 20090610 . 092732 . 6908 . 0001 . txt 

4. Add the file to the archive that contains the workspace data. 

13.3.2 Searching for IBM MustGather information 

The IBM support website contains additional documentation for preparing data 
for service. You can search the IBM website for CICS Explorer MustGather. 


13.4 Plug-in specific issues 

In this section, we describe special cases that affect the plug-ins. 
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13.4.1 Performance Analyzer 


In this section, we discuss the Performance Analyzer. 

CSV file corruption 

It is critical that the csv file that is used in the PA plug-in was created by the PA 
runtime and was not modified in any way. Unfortunately, this includes a situation 
when a csv file is viewed using Excel. Excel restructures the time field in a 
manner that makes it relatively unusable by the PA plug-in. If when the 
application is closed Excel offers to save updates even though none were 
knowingly made, the file is corrupted and must be downloaded from the server 
again. 


13.4.2 CSV file size and CICS Explorer runtime memory 

The CSV file is held in java memory and is therefore restricted by factors that are 
external to the Explorer, including system memory. If you are using csv files, this 
might cause OutOfMemory Exceptions when an inadequate Java heap size is 
allocated. There is no hard rule to what needs to be allocated and many users 
find that the default maximum heap size is perfectly sufficient. However, it might 
be necessary in some circumstances to increase the value: 

1 . In a Windows or Linux command line, change the directory to the directory 
where the cicsexplorer.exe (cicsexplorer on Linux) file is located. 

2. Start the CICS Explorer by typing the following command: 
cicsexplorer -vmargs -Xmx512m 

3. Alternatively, you can modify the cicsexplorer.ini file in the CICS _Explorer 
subdirectory to add the following information: 

- -vmargs 

- -Xms128m 

- -Xmx512m 

4. Start the CICS Explorer as normal. 
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Part 2 


Scenarios 


In this part, we cover the following scenarios: 

► MQ application migration 

► CICS resource cleanup 

► CICS Performance 

► CICSPlex SM enablement using the CICS Explorer 

► CICS resource manipulation 
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14 


CICS Explorer - MQ 
application migration 


In CICS TS V3.2, MQ calls are now run on the open L8 TCB; therefore, you must 
be aware of the MQ applications that you have and the implication of defining the 
programs as THREADSAFE. 

In this chapter, we show how you can use the CICS Explorer and CICS Tools 
plug-ins to assist you in identifying MQ applications to migrate from CICS TS 
V3.1 to CICS TS V4.1 . The same benefits can be obtained if migrating to CICS 
TS V3.2. 

We use: 

► The CICS IA and CICS CM plug-ins to identify MQ applications that can 
benefit from migrating to CICS TS V4.1 . 

► The CICS IA plug-in to investigate threadsafe requirements. 

► The CICS PA plug-in to view before and after performance measurements. 

We also show the integration between the plug-ins themselves and the base 
CICS TS Explorer. 
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14.1 Identifying MQ Applications 


In this section, we use the CICS IA plug-in to identify programs and transactions 
that contain MQ commands. 

We assume that you captured CICS IA data collector data with the ‘Detailed’ 
option on for ‘Programs’ and that we collected ‘Command flow’ detail for 
transaction MAIL. 

For more information about data collection in CICS IA, refer to the CICS IA V3. 1 
User Guide, SC34-6992-00. 

Before using the CICS IA Explorer plug-in, first ensure that you are connected to 
the CICS IA database. See 3.5, “Using plug-ins” on page 73 in Chapter 3 
Implementing CICS Explorer. 

Selecting the IA perspective 

To select the IA perspective: 

1 . After you are connected go to the CICS IA perspective, from the Explorer 
select Window ->• Open Perspective ->• Other ->• CICS IA. See Figure 14-1 . 



Figure 14-1 Open I A Perspective 

2. In the IA perspective, create a new query to identify transactions and 
programs that use MQ resources. Select the Queries folder, right-click the 
MQ folder, and select New ->• MQ Query, as shown in Figure 14-2 on 
page 283. 
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3. Press Enter, and select the query name, the columns to show, and the filter 
criteria, as shown in Figure 14-3. 



Figure 14-3 MQ Query edit panel 
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4. Select OK to save the query, and then run the query as shown in Figure 14-4. 



The results of the query are shown in the resources folder, as shown in 
Figure 14-5 on page 285. 
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Figure 14-5 Results of the MQ query 


We have one transaction, MAIL, in region IYDZEJ0B. To migrate this transaction 
and the associated resources we must obtain more information before using the 
CICS CM plug-in. 


14.2 Obtaining more information about the MAIL 
transaction 

The CICS IA exits can collect detailed information about a number of resources, 
which include: 

► CICS Applid 

► Transactions 

► Programs 

► Exits 

► TSqueues 

► TDqueues 

► Webservices 

► Files 
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For more information about data collection in CICS IA, refer to the CICS IA V3. 1 
User Guide, SC34-6992-00. 

To show the detailed information, we must turn on the Properties View. Select 
Window Show Property View, as shown in Figure 14-6. 


Window Help 
Open perspective 
Show View 

Save Perspective As. 
Reset Perspective . . . 
Navigation 


Figure 14-6 Select property view 


A new view is displayed in your perspective and it is populated when ever you 
select a resource type for which detailed information is captured. In Figure 14-7, 
we selected the applid, IYDZEJ01 . 

The CICS region uses a CSD file called REDTOOLS.REDDEV31 .DFHCSD, 
which we use later when we look at the CICS CM plug-in. 


iZl Properties S3 \ 
Property 

S Region IYDZEJOB 
Aff coll lastsave 
AfTcoll laststart 
Applid 

Cics_release 
Csd group listl 
Csd group Iist2 
Csd group Iist3 
Csd group Iist4 
Csd name 
Dep coll lastsave 
Dep coll laststart 
Homesysid 
Storage protect 


Value 

0001-01-01 00:00:00.0 

0001-01-0100:00:00.0 

IYDZEJOB 

0640 

DFHLIST 


REDTOOLS.REDDEV31. DFHCSD 
2009-06-05 11:43:37.0 
2009-06-05 11:42:41.0 
EJ0B 

INACTIVE 


Figure 14-7 Detail view for APPLID IYDZEJOB 


We can also see the properties for a program, for example, in Figure 14-8 on 
page 287 we selected program TST4CVD1 . For CICS TS V3.2 and above we 
show the Library database name and library. 
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We also must know what resources are used by transaction MAIL to migrate 
themtoCICSTS V4.1: 

1 . Right-click the MAIL transaction, and select Uses Resource -» Specific 
region, as shown in Figure 14-9 on page 288. 
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Figure 14-9 Show resource to transaction MAIL 


2. Select region IYDZEJ0B, as shown in Figure 14-10. 



Figure 14-10 Select region IYDZEJ0B 

The results are shown in the Uses view, as shown in Figure 14-11 on page 289. 
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Figure 14-11 Resources used by transaction MAIL 


Notice that there are a number of resources used by the MAIL application. For 
more information about how to navigate the Uses view, refer to Chapter 6, “CICS 
Explorer IA plug-in familiarization” on page 137. 

We gathered the information that we require for using the CICS PA plug-in. 
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14.3 Locating the MQ Application in CICS CM 


Now that we identified our MQ application, we can use the CICS CM plug-in to 
search for its resource definition. In this example, our application consists of: 

► One transaction: 

- MAIL 

► Five programs: 

- TST4CVD1 

- TST4CVD2 

- TST4CVD3 

- TST4CVD4 

- TST4CVD5 

Before using the CICS CM Explorer plug-in, first ensure that you are connected 
to the CICS CM server. See 3.5, “Using plug-ins” on page 73. 

To locate the MQ Application in CICS CM: 

1 . Select the CM perspective, and from the Explorer select Window ->• Open 
Perspective -» Other CICS CM. 

2. First we must select a configuration to work with. From CICS IA we know that 
the CSD in use is REDTOOLS.REDDEV31 .DFHCSD. We must select this 
configuration in the CICS CM perspective. In the Configurations view, select 
the configuration for CSD REDTOOLS.REDDEV31 , as shown in 

Figure 14-12. 



Figure 14-12 Select configuration 
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3. To search for a resource, click the torch in the top left corner of your 
perspective, as shown in Figure 14-13, and enter the resource name for 
MAIL 



Figure 14-13 Search for MAIL 


4. The results of the search are displayed in the Search Results. To show the 
group, click Show Groups, as highlighted in Figure 14-14. We can see that 
transaction MAIL is in MAILGRP. 



Figure 14-14 Results of the search 

5. We now need to look at what other resources are stored in this group. 
Right-click the group, and select Show all resources, as shown in 
Figure 14-15 on page 292. 
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Figure 14-15 Show all resources for group MAILGRP 

The results are shown in the same view, as shown in Figure 14-16. 


4 - □ Properties 


All resources for MAILGRP, Group MAILGRP 

0) 

0 S! MAILGRP (7) 

0 & Map Set Definitions (1) 

H CSQ4VDM 

0 & Program Definitions (5) 

IH TST4CVB1 
[3TST4CVB2 
IU TST4CVB3 
13 TST4CVB4 
Hi TST4CVB5 
Transaction Definitions (1) 
MAIL 



Figure 14-16 All resources in group MAILGRP 


We have now established what resource group we need to migrate to CICS TS 
V4.1 . We can now use the CICS CM ISPF to package and migrate this group to 
our CICS TS V4.1 development region. For more information about using change 
packages, refer to the CICS CM User Guide, GC34-7048-00. 
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14.4 Looking at performance data for the MAIL 
transaction 


Before migrating the MAIL application, we used CICS PA to gather performance 
data on the CICS region REDDEV31 . For more information about collecting 
CICS PA performance data, read the CICS PA User’s Guide, SC34-7046-01. 

14.4.1 Performance data for MAIL on CICS TS V3.1 

For a given transaction, you can link to the CICS PA performance data from the 
IA or CM perspective. In the following example, we go from the CM perspective: 
1 . In the Search Results view, right-click the MAIL transaction, and select 
Performance History CPU Time, as shown in Figure 14-17. 



■f Search Results S3 '\JS Properties 



All resources for MAILGRP, Group MAILGRP 

(7) 

- 

1 0 I] MAILGRP (7 
0 & Map Set 

' Open 



eacsd 

0 & Program 
HI TST 

X Delete 



Dependencies ► 

Find ► 


[Bjo Threadsafe 

Performance history ► 


U|b Storage 




CPU time 

Add to Group... 


lB|o Response time 

Remove from Group 


U|o File usage 



Figure 14-17 Link to Performance Data from CICS CM 


2. A Restrict analysis time period is displayed. Select the date and time, as 
shown in Figure 14-18 on page 294. 
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Figure 14-18 Select date and time options 


3. After you select the time range, click OK. You should now see a graph similar 
to the one in figure Figure 14-19 on page 295. 
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4. For more information, double-click any of the columns, and then maximize the 
view. Figure 14-20 on page 296 shows the Threadsafe report for transaction 
MAIL. As you can see from Figure 14-20 on page 296, you can choose other 
report types, such as CPU time or response times. 
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Figure 14-20 Detailed report for transaction MAIL in REDEV31 


Notice that our MQ Mail transaction in REDEV31 runs in the QR mode only. 
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14.4.2 Performance data for MAIL on CICS TS V4.1 


We migrated the MAIL application to CICS TS V4.1 on region REDEV41. We 
must collect new PA and IA data for this region. 

For CICS IA, we also captured Command Flow data for transaction MAIL. 

We now return to the IA perspective and look at the MAIL transaction in region 
REDEV41 : 

1 . Select the IA perspective, and in the ‘regions’ folder, select the transactions 
used in region IYDZEJ02, as shown in Figure 14-21. 



Figure 14-21 Select transaction in region IYDZEJ02 

2. In the Transactions folder, in the input area enter M* to show only transactions 
that start with M*, as shown in Figure 14-22 on page 298, which also shows 
the properties for region IYDZEJ02. We can see that it is a CICS TS V4.1 
region, and the CSD is called REDTOOLS.REDDEV41 .DFHCSD. 
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1^ Programs ED Transactions “ E3 
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M* | in Region [v] IYDZEJ02 ( 1) 
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Aff coll lastsave 2009-06-02 13:23:09.0 

Aff coll laststart 2009-06-02 13:22:03.0 

Applid IYDZEJ02 

Cics_release 0660 

Csd group listl DFHLIST 

Csd group Iist2 REDLIST 

Csd group list3 
Csd group lisM 

Csd name REDTOOLS.REDDEV41.DFHCSD 

Dep coll lastsave 0001-01-01 00:00:00.0 
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Homesysid EJ02 

Storage protect INACTIVE 


Figure 14-22 Transactions folder 


3. We now look at some CICS PA data for the MAIL transaction in region 
REDDEV41 . This time we link from the IA perspective. Right-click the MAIL 
transaction, and select Performance History CPU time, as shown in 
Figure 14-23. 



4. Enter the date and time for the CICS PA collection in region REDDEV41 , and 
then double-click the instance to obtain the threadsafe report, as shown in 
Figure 14-22. 
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We can now see that the MAIL transaction spends nearly half of its time on an 
open L8 TCB, which reduces the time on the QR TCB. 

We can also see 46 TCB mode switches. We now need to ask the following 
question: 

Can we reduce the amount of TCB mode switches? 

To answer this, we must understand the resources and commands that are 
issued by the MAIL transaction. We also must know how the transaction is 
currently defined. 
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14.5 Can we make the MAIL transaction threadsafe 


First we obtain how the MQ programs that are associated with the MAIL 
application are defined. In particular, we are interested to see the ‘Concurrency’ 
value for the programs. We use the base CICS Explorer to look at the attributes 
of these programs: 

1 . Select the default CICS SM perspective. We explain how to connect to the 
base server in Chapter 2, “Getting started with CICS Explorer” on page 19. 

2. In the CICS Explorer view, select region REDDEV41 , as shown in 
Figure 14-25. 



Figure 14-25 Select region REDDEV41 

3. Select the transaction view with a filter of M*, as shown in Figure 14-26. 


£l Regions % Tasks 00 ISC/MRO Connections j § Terminals | Up Files % 


.11 Context: REDDEV41. Resource: LOCTRAN. 2 records collected at 150un-2009 14: 19:29 


Use Count | Program 


Figure 14-26 Transaction view 


Transact... Purgeability Dumping Routing 

DFKTCL00 NOTPURG... TRANDUMP STATIC 

DFHTCL00 NOTPURG... NOTRAND... STATIC 


4. Before looking at CICS IA data, we can look at the program attributes for 
program TST4CVD1 . Right-click the entry for transaction MAIL, select Open 
Related Program, as shown in figure Figure 14-27 on page 301. 
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The program attributes are displayed, as shown in figure Figure 14-28 on 
page 302. 
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Figure 14-28 Program details for TST4CVD1 


We can see that the program is defined with a concurrency of QUASIRENT. 

To ascertain whether we can define the programs that are associated with MAIL 
as THREADSAFE, we can now use CICS IA: 

1 . We can link to the CICS IA data and view resources that are used by this 
transaction from the Transaction view. Right-click the transaction mail, and 
select Dependencies Uses Resources, as shown in figure Figure 14-29 
on page 303. 
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2. Alternatively, we can open the CICS IA perspective and interrogate the IA 
data from there, as we described in “Using the CICS IA Command flow 
feature” on page 305. 



3. You can now see a Uses View with resource information for the MAIL 

transaction collected by the CICS IA product. You can expand the Resources 
Used view to show the resource names and commands, as shown in figure 
Figure 14-30 on page 304. 

The first task when looking for programs that we can make threadsafe is to look 
for shared resources, such as the CWA. In an open TCB environment, multiple 
tasks can potentially access shared resources simultaneously, which could lead 
to loss of data integrity. We must examine the MAIL application programs to 
ensure that they do not use any of the following CICS commands: 

► ADDRESS CWA 

► EXTRACT EXIT 

► GETMAIN SHARED 

As shown in Figure 14-30 on page 304, for installations that have an application 
standard that allows the use of assembler data tables as a form of shared 
storage, add: 

LOAD PROGRAM 
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In the case of the MAIL application, we can see that it consists of only four 
programs, as shown in figure Figure 14-31. 

We can see from Figure 14-31 that there are no CWA, EXIT, or STORAGE 
resources. 


JH* Uses ° □ 

Transaction(MAIL) in Region IYDZE302 (15) 

Resources used 

By Resource 

$ & Program (4) 

15 I?} T5T4CVD1 (1) 
T5T4CVD2 (2) 
ffi [gj TST4CVD3 (2) 
ffl [g} TSTT4CVD4 (2) 
ffi & TSQUBJE AUX (1) 
$ MAPSET (1) 

SI &Map (5) 

a & UOW ( 1 ) 

Si & TEXT (1) 



Figure 14-31 Programs used 


We can fully expand the program calls to look for any LOAD commands, as 
shown in Figure 14-32 on page 305. You see that some of the programs have a 
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‘blank’ command that indicates that the program was started as a result of a 
transaction start, and the transaction was MAIL. 



Figure 14-32 Program commands 


So by exploring the MAIL transaction, we can ascertain that it is a good 
candidate to be made threadsafe because it contains MQ commands, and it has 
no shared resources. 

In the next section, we use the CICS PA plug-in to review the performance data 
after making the MAIL programs THREADSAFE. 

Using the CICS IA Command flow feature 

In CICS IA V3.1 , we provide a new feature to capture CICS API and APIs, MQ 
calls, IMS calls, and DB2 calls in chronological order. For information about how 
to capture command and load command flow data, refer to the CICS IA User 
Guide. To use the CICS IA Command flow feature: 

1 . From the Transactions folder, right-click the MAIL transaction, and select 
Show Command Flow runs, as shown in Figure 14-33 on page 306. 


Chapter 14. CICS Explorer - MQ application migration 305 



Figure 14-33 Select Command Flow runs 


2. The Resources View is populated. Expand the tree for MAILTS41 , as shown 
in Figure 14-34. 


i_j Resources £3 0 0 

° □ 

Command Flow runs for TRANSID (MAIL) 

(46) 

S MAIL ON 31 (17) 

0 MAIL0N41 (1) 

® MAIL41QR (27) 

0 J4AIL41TS (1) 

0 2009-06-0409:47:31.051835 (1) 

O TASKID (005848 1C) 



Figure 14-34 Command Flows for transaction MAIL 


3. Right-click the TASKID, and select Show Execution, as shown in 
Figure 14-35 on page 307. 
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Figure 14-35 Select Show Execution 


A new Command Flow view is opened, as shown in Figure 14-36. 



Figure 14-36 Command Flow view 


The Command Flow view, Figure 14-36, consists of three sections: 

► The left most section shows the commands that the TCB Modes use. In 
Figure 14-36, we show the commands used in the ‘L8’ TCB. 
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► The middle section shows the commands that cause a TCB switch. In this 
case, we are looking at the commands that caused a switch from L8 back to 
QR. We can see that these are SEND maps and text. 

► The third right most view shows the execution tree itself. We can see here that 
transaction MAIL starts program TST4CVD1 . If we select a command in 
either of the other views, it highlights this command in the execution tree. In 
this example, we selected the SEND CSQ4VD1 command in the TCB Mode 
Switches view. Notice in the execution tree that this SEND MAP occurs after 
an MQOPEN is running on TCB ‘L8’. 
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14.6 Using CICS PA to analyze the (threadsafe) MAIL 
application 


We use the Resource perspective to look at data stored in CSVs. You can store 
your data in a DB2 database. For more information about setting up the CICS PA 
data, refer to Chapter 8, “CICS Explorer PA plug-in familiarization” on page 191 . 
1 . The CICS PA performance data collected after making the MAIL application 
threadsafe is stored in the REDTOOLS.MAIL41TH.CSV. We select this CSV 
file, as shown in Figure 14-37. 



You can expand each time slot further by region and the transaction, as 
shown in Figure 14-38 on page 310. 
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Figure 14-38 Select time and transaction 


2. Select a CICS PA ‘CPU time’ report. Right-click the MAIL transaction, as 
shown in Figure 14-39. 
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Figure 14-39 Select CPU time report 


A new folder for the ‘CPU time’ report is displayed, as shown inFigure 14-40 
on page 31 1 . 
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3. 


e* . 


•CSVIYDZEJ02, MAIL+ 



10:40:00.000 




Figure 14-40 CPU Time report for MAIL 

For more information about a particular instance, right-click an entry, and 
select Detailed breakdown, as shown in Figure 14-41 on page 312. 
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Figure 14-41 Select Detailed breakdown 


The Detailed breakdown shows us the ‘Threadsafe’ chart for the MAIL 
application after it is made threadsafe, as shown in Figure 14-22 on 
page 298. 
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We can see from this chart that by making the MAIL programs threadsafe, we 
reduced the number of TCB switches from 46 to 1 8. We can also see that the 
application spends more time on the open L8 TCB, which frees up the QR TCB. 
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15 


CICS Explorer clean up 
scenario 

In this chapter, we discuss a scenario that shows the use of the CICS Explorer 
and CICS Tools plug-ins to analyze CICS resource definitions with a view to 
cleaning up or tidying these up. 

In most CICS environments, whether it is development, test, or even production 
(in some cases), there are redundant definitions that remain on CSDs for years. 
Often, systems programmers were reluctant to delete any definitions because 
there was no easy way for them to determine if the definitions were occasionally 
used. 

In this chapter, we show that with the help of the CICS Explorer and the plug-ins 
for CICS CM and CICS IA, you can quickly identify duplicate or orphaned 
resources and then obtain if they are in use now or if they were ever used. 
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15.1 Orphaned resources 


We first look at how with using CICS CM, you can identify all orphaned groups of 
resources within one or more CSDs. 

To identify all orphaned groups of resources: 

1 . Using the CICS CM plug-in, first ensure that you are connected to the CICS 
CM server. See Figure 15-1 on page 316 for details. 

2. Open the CICS CM perspective by clicking Window Open Perspective -> 
Other CICS CM. Figure 15-1 shows the CICS CM perspective. 



Figure 15-1 Selecting the CICS CM perspective 


3. Within the CICS CM perspective, select the CICS CM configuration (CSD) 
that you want to work with. We select CSD REDCSD41 . 


Note: If you want to work with several configurations at a time, you can 
select multiple configurations, including CICSPlex SM Contexts and CSDs. 


Figure 15-2 on page 317 shows the CICS Explorer full screen with the CICS 
CM perspective. 
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Figure 15-2 CICS CM perspective 


4. Right-click, and select Cleanup -> Show Orphaned Groups, as shown in 
Figure 15-3 and Figure 15-4 on page 318. This action populates the bottom 
right view with all of the orphaned groups within this CSD, as shown in 
Figure 15-5 on page 318. 


Show All Resources 
Cleanup ► 

Search ► 

Figure 15-3 Clean-up option 

5. Let us look at orphaned group Mail. Click this group in the list of orphaned 
groups, and the history of changes to definitions in this group is populated in 
the middle pane, shown in Figure 15-5 on page 318. 
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6. Expand each entry in the History View to see what changes were made to 
these resource definitions, including the create date and change date. 


Show Resources With Unique Names 
Show Duplicate Resources by Name and Type 

Show Orphaned Groups 

Figure 15-4 Orphaned Groups option 



Figure 15-5 Orphaned groups in configuration REDCSD41 


7. In the Resources View, select the Transaction Definitions tab, and the Mail 
transaction is displayed. Right-mouse click the Mail transaction definition, and 
select Dependencies -> Uses Resources to seamlessly invoke CICS IA and 
see the resources used by this transaction and the call tree of program 
execution, as shown in Figure 15-6 on page 319. 
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Figure 15-6 Resources used and call tree of program execution 


8. We now invoke the CICS IA perspective for further analysis of this application. 
Click the CICS IA tab on the top right side of the perspective, which we show 
in Figure 15-6. 

9. In the CICS IA perspective, click the Transactions tab, and specify a filter of 
M* in the box to narrow your search for this transaction, as shown in 
Figure 15-7 on page 320. 
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Figure 15-7 Mail transaction in CICS IA perspective 


10. Right-mouse click the Mail transaction, and select Show View and 
Transactions, as shown in Figure 15-8. 


Used By Programs ► 

Used By Transactions ► 
Uses Resources ► 




Show View ► 

1^1 Regions 




Tasks 




Transactions 


Transaction Definitions 


Figure 15-8 Show View and Transactions in the CICS I A perspective 

We invoke the CICS SM perspective and determine which regions this 
application runs in. 
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In Figure 15-9, the view on the far right side of the perspective shows the 
CICS regions in which transaction MAIL is installed. 



Figure 15-9 Details of regions in which the MAIL transaction is installed 


1 1 .From the CICS IA perspective, select Show Properties View, as shown in 
Figure 15-10. 



Open perspective 
Show View 


Save Perspective As... 

Reset Perspective... 

Navigation > 

Preferences 

Show Properties View 

Figure 15-10 Access the Show Properties view 
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Figure 15-1 1 shows details about the First run and Last run of the transaction. 



Figure 15-11 Details of First run and Last run of the transaction 


By working through this scenario, we determined that the MAIL application 
group, although orphaned, is still used. The cleanup action here is to add the 
group to a grouplist for the relevant CICS region. 

By working through the other groups in the list of orphaned groups and following 
the instructions in this section, we can quickly obtain if the groups are in use and 
then take the appropriate action. 


322 IBM CICS Explorer 


15.2 Duplicate resources 


Another capability that the CICS CM plug-in provides is finding duplicate 
resources in a CSD or CICSPlex SM BAS repository. 

To find duplicate resources in a CSD or CICSPlex SM BAS repository: 

1 . From the CICS CM perspective, right-click the configuration that you want to 
work with. Select Cleanup -> Show Duplicate Resources by Name and 
Type, as shown in Figure 15-12 and Figure 15-13. 


Show All Resources 
Clean Up 
Search 


Figure 15-12 Cleanup 



Figure 15-13 Duplicate Resources by Name and Type 

A list of resource definitions within groups that have duplicate resources of the 
same name and type within the repository is displayed, as shown in 
Figure 15-14 on page 324. 
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Figure 15-14 Duplicate Definitions found 


2. Expand each group, right-click a resource definition, and select Find 

Similar resources to list all resources of the same name and type within the 
repository, as shown in Figure 15-15 on page 325. 
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Figure 15-15 Finding similar resources 


In Figure 15-16 on page 326, notice that the file ACCTFIL was found in three 
different groups. 
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Figure 15-16 Duplicate file 


3. From here you can right-click, and delete the file definition in group XXX, if 
you believe that this definition is not used. Figure 15-17 on page 327 shows 
an example of deleting a duplicate file. 
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Figure 15-17 Delete a duplicate definition 


4. When you select the Delete option, the Confirm Delete prompt is displayed, 
as shown in Figure 15-18. Click OK to delete the resource definition. 



Figure 15-18 Delete confirmation 
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CICS Explorer performance 
scenario 

In this chapter, we discuss how you can use the CICS Explorer together with the 
CICS PA plug-in to navigate through the large amount of performance data that is 
available in a complex CICS configuration. 

As we described in Chapter 8, “CICS Explorer PA plug-in familiarization” on 
page 191 , using CICS Performance Analyzer for z/OS V 3.1 you can create 
performance data extracts in the form of CSV files or DB2 tables. These data 
extracts are typically for a subset of the large amount of SMF data that is 
recorded in most CICS installations. 

By using the CICS Explorer, you can identify CICS system level performance 
problems without having to delve into large amounts of CICS monitoring and 
statistics data. 

Using the CICS PA plug-in to analyze the data extracts that CICS PA creates you 
can create charts and reports that can help to identify performance bottlenecks 
within specific transactions. 


© Copyright IBM Corp. 2010. All rights reserved. 


329 




16.1 Resolving system performance problems 


The CICS Explorer provides a number of alerts for performance problems at the 
system level, such as: 

► Short on Storage 

► System dump in progress 

► Transaction dump in progress 

► System has reached MAXTASKS limit 

► Tasks stalling because of resource contention 

In Figure 16-1 , we create a Short on Storage condition using transaction SOS7, 
which GETMAINs large amounts of CICS DSA. 

After running the transaction, we immediately see the alert in the CICS Explorer 
view, as shown in Figure 16-1. 



Figure 16-1 SOS Condition 
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If we invoke the Operations and Tasks view and specify a Transaction name filter 
of SOS7, we can display the status of this task, as shown in Figure 16-2. 



Figure 16-2 Status of task 


Right-click the task to select the option to Purge, Force Purge, or Kill the task, as 
shown in Figure 16-3. 



Figure 16-3 Options to remove the task causing SOS 
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We tried the Purge option and received the response in Figure 16-4. 



Figure 16-4 Purge response 

We then used the Force Purge option, and the task was purged successfully. The 
SOS condition was rectified as confirmed by the Event view in the CICS Explorer. 

To investigate the problem further, you can click the Transactions tab in the 
CICS Explorer and look at the attributes of the SOS7 transaction. We 
double-clicked transaction SOS7 and could see all of the runtime attributes of 
this transaction, as shown in Figure 16-5 on page 333. 
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Figure 16-5 Runtime attributes of transaction SOS7 
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16.2 Drilling down into transaction detail 


To obtain further information about transaction SOS7, we right-click the 
transaction in the CICS CM perspective, and select Dependencies ->• Uses 
Resources, as shown in Figure 16-6. 



Figure 16-6 Finding details of Resources used 


The CICS IA perspective is invoked and provides further details about this 
transaction. As shown in Figure 16-7 on page 335, transaction SOS7 runs 
program REDTSOS7, which issues a number of API commands including a 
GETMAIN. 


334 IBM CICS Explorer 



Figure 16-7 Detailed view of transaction SOS7 

To look at the performance profile for this transaction, from the CICS CM 
perspective and the Transaction view, right-click transaction SOS7, and select 

Performance history Storage. 

Looking at the transaction detail, we can see that the EUDSA high-water-mark 
was reached four times, and the ECDSA high-water-mark was reached five 
times. 

Figure 16-8 on page 336shows the storage usage detail for transaction SOS7. 
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Figure 16-8 Storage usage detail for transaction SOS7 

Analyzing transaction performance 

In this scenario, we provide an example of navigating through the CICS PA 
plug-in to analyze the performance characteristics of a transaction. 

We first ensure that the connection from the CICS PA plug-in to the DB2 
database that contains the CICS PA HDB data is active. See Chapter 8, “CICS 
Explorer PA plug-in familiarization” on page 191. 

Next, we invoke the CICS PA perspective. We expand the CICS Explorer 
Redbooks System.cpa folder to see the dates on which SMF data was loaded 
into a CICS PA HDB and then exported to a DB2 table. 
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We want to analyze a set of transactions that executed on the 1 1th of June 2009, 
so we right-click the folder for this date, and select Sheet View. Figure 16-9 
shows the Sheet View. 



From the Sheet View, we can select a set of transactions for a particular date and 
time and start further analysis. To do this, we simultaneously press the Shift key 
and the Scroll Down key to select a set of transactions to analyze. 

Having selected our set of transactions, we right-click and invoke other views to 
drill down into the performance profile for these transactions, as shown in 
Figure 16-10 on page 338. 
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Figure 16-10 Drilldown into performance analysis from the Sheet view 


In our case, we wanted to start with details of response times for these 
transactions, so we click Response time to invoke the bar chart view for these 
transactions. 

Looking at the response times for the MAIL transaction, we immediately see a 
significant difference in response times for this transaction during two separate 
time intervals. 
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By hovering the mouse cursor over the bars, we saw that the suspend time 
average during one interval was 14.531239 seconds and during another it was 
8.996642 seconds. 

Figure 16-1 1 shows the response times for the Mail transaction. 



Figure 16-11 Response times for Mail transaction 


By double-clicking each bar we can invoke the detail breakdown view. Then we 
select Response time to get the complete Response time breakdown for that 
interval. 

As we can see from the detailed breakdown for the 10:10 am interval, the User 
Dispatch time was 0.026304 seconds and the suspend time was 14.531239 
seconds, as shown in Figure 16-12 on page 340. 
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Figure 16-12 Response time breakdown for 10:10 interval 


As we can see from the detailed breakdown for the 10:15 am interval, 

Figure 16-13 on page 341 , the User Dispatch time was 0.015940 seconds and 
the suspend time was 8.996642 seconds. 

From the detailed breakdown views, we can determine a lot of information about 
the performance profile for this transaction during the two intervals using the 
Threadsafe, CPU time, Storage, and File usage views if appropriate. 
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Figure 16-13 Response time breakdown for 10:15 interval 


To determine the cause of the long Suspend time during the 10:10 interval, we 
can look again at the Sheet View by clicking the appropriate tab. 

As we can see from the Sheet View and by scrolling right to the “Terminal Control 
I/O wait time average” column the difference in Suspend time for the MAIL 
transaction for the two intervals is entirely due to Terminal Control I/O wait, as 
shown in Figure 16-14 on page 342. 
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Figure 16-14 Terminal Control I/O Wait details for MAIL transaction 

To complete our analysis and to confirm our findings, we submit a Wait Analysis 
report using the CICS PA ISPF dialogue for the intervals that we looked at here. 

The output from the wait analysis report confirms what we see in the CICS PA 
plug-in Sheet View. The large response time differences are due to differences in 
values for Terminal Control I/O waits for the two intervals we analyzed. 

Example 16-1 shows the wait analysis for MAIL transaction at 10:00. 

Example 16-2 on page 343 shows the wait analysis for MAIL transaction at 
10:15. 


at 10:00 
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TCIOWTT T« 
DSCHMDLY R 


DSPDELAY First dispatch wait time 



TSIOWTT VSAM TS I/O wait time 




Example 16-2 Wait Analysis for MAIL transaction at 10:15 

Start=10 : 15 : 00 APPLID=IYDZEJ02 Tran=MAIL lnterval=00 : 05 : 00 
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CICSPlex SM enablement 
using the CICS Explorer 


One of the functions of CICSPlex SM is to implement dynamic workload 
management within CICS. In this chapter, we review the various factors that you 
must take into account when delivering such a solution. We also discuss how we 
can identify these solutions and address them using the CICS Explorer. 

When a program or transaction in CICS uses an external resource, such as a file 
or temporary storage, this creates an affinity within the transaction to that 
resource. CICS Interdependency Analyzer gives us the ability to analyze affinity 
data. The affinity data is loaded into DB2 databases, on which you can perform 
SQL queries and from which you can produce detailed reports. 
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17.1 Overview of transaction affinities 

CICS transactions use many different techniques to pass data from one 
transaction to another. Some techniques require that the transactions that are 
exchanging data must execute in the same CICS region and therefore impose 
restrictions on the dynamic routing of transactions. If transactions exchange data 
in ways that impose such restrictions, there is said to be an affinity between 
them. 

There are two categories of affinity: 

► Inter-transaction affinity 

► Transaction-system affinity 

The restrictions on dynamic routing caused by transaction affinities depend on 
the duration and scope of the affinities. Clearly, the ideal situation for a dynamic 
routing program is for there to be no transaction affinity at all, which means there 
is no restriction in the choice of available target regions. However, even when 
transaction affinities do exist, there are limits to the scope of these affinities that 
are determined by the: 

► Affinity relations 

► Affinity lifetime 

CICS IA cannot detect affinities in the following types of dynamically routed 
requests: 

► Non-terminal-related START requests 

► Distributed program link (DPL) requests 

► Method requests for enterprise beans or CORBA stateless objects 

For these types of dynamically routed requests, review your application to 
determine whether it is suitable for dynamic routing. 

17.1.1 Inter-transaction affinity 

An inter-transaction affinity is an affinity between two or more CICS transactions. 
It is caused by the transactions using techniques to pass information between 
one another or to synchronize activity between one another in a way that requires 
the transactions to execute in the same CICS region. 
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Inter-transaction affinities that impose restrictions on the dynamic routing of 
transactions, can occur in the following circumstances: 

► One transaction terminates, leaving “state data” in a place that a second 
transaction can access only by running in the same CICS region as the first 
transaction. 

► One transaction creates data that a second transaction accesses while the 
first transaction is still running. For this to work safely, the first transaction 
usually waits on an event, which the second transaction posts when it has 
read the data that the first transaction created. This synchronization 
technique requires that both transactions are routed to the same CICS region. 

17.1.2 Transaction-system affinity 

A transaction-system affinity is an affinity between a transaction and a particular 
CICS region. It is caused by the transaction interrogating or changing the 
properties of the CICS region. 

Transactions with an affinity to a particular CICS region, rather than to another 
transaction, are not eligible for dynamic transaction routing. Typically, they are 
transactions that use CICS SPI commands, such as EXEC CICS INQUIRE or 
SET or that depend on global user exit programs. 


17.1.3 Affinity relations 

When a transaction is associated with an affinity, the affinity relation determines 
how the dynamic routing program selects a target region for an instance of the 
transaction. An affinity relation can be classified as one of the following relations: 
Global A group of transactions in which all instances of all 

transactions in the group that are initiated from any 
terminal, or are BTS or Link3270 transactions, must 
execute in the same target region for the lifetime of the 
affinity. The affinity lifetime for global relations can be 
“system” or “permanent.” 

BAPPL All instances of all transactions in the group are 

associated with the same CICS Business Transaction 
Services (BTS) process. There might be many different 
user IDs and terminals that are associated with the 
transactions that are included in this affinity group. 
LINK3270 All instances of all transactions in the group are 

associated with the same Link3270 bridge facility. 
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LUname A group of transactions in which all instances of all 

transactions in the group that are initiated from the same 
terminal must execute in the same target region for the 
lifetime of the affinity. The affinity lifetime for LUname 
relations can be “pseudoconversation,” “logon”, 
“pseudoconversational”, “system,” or “permanent.” 

UserlD A group of transactions in which all instances of the 

transactions that are initiated from a terminal and 
executed on behalf of the same user ID must execute in 
the same target region for the lifetime of the affinity. The 
affinity lifetime for userlD relations can be 
“pseudoconversation “signon,” “system,” or “permanent.” 


17.1.4 Affinity lifetimes 


The affinity lifetime determines when the affinity is ended. An affinity lifetime can 
be classified as one of: 


System 


Permanent 


Process 

Activity 

Facility 


The affinity lasts for as long as the target region exists and 
ends whenever the target region terminates (at a normal, 
immediate, or abnormal termination). The resource 
shared by transactions that take part in the affinity is not 
recoverable across CICS restarts. 

The affinity extends across all CICS restarts. (The 
resource shared by transactions that take part in the 
affinity is recoverable across CICS restarts.) This is the 
most restrictive of all the inter-transaction affinities. 

The affinity exists until the BTS process completes. 

The affinity exists until the BTS activity completes. 

The affinity exists until the Link3270 bridge facility is 
deleted. 


Pseudoconversation The (LUname or userlD) affinity lasts for the whole 
pseudoconversation and ends when the 
pseudoconversation ends at the terminal. 

Logon The (LUname) affinity lasts for as long as the terminal 

remains logged on to CICS and ends when the terminal 
logs off. 

Signon The (userlD) affinity lasts for as long as the user is signed 

on, and ends when the user signs off. Note that this 
lifetime is only possible in those situations where only one 
userlD is permitted. Signon lifetime cannot be detected if 
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multiple users are permitted to be signed on with the 
same userlD at the same time. 


Note: If an affinity is both “userlD” and “LUname” (that is, all instances of all 
transactions in the group were initiated from the same terminal and by the 
same user ID), “LUname” takes precedence. 


17.2 Running CICS Interdependency Analyzer for 
affinities 


In the first instance, we must run the collector component of CICS 
Interdependency Analyzer for z/OS against our candidate application. We chose 
a single application to analyze to prepare this for CICSplex enablment. 

We need to set the correct parameters in the collector panel through the 
transaction CINT, as shown in Figure 17-1 . 


CIU290 CICS Interdependency Analyzer for z/OS - V3R1M0 2009/06/01 

Resource Options for 09:28:10AM 

CICS Sysid: EJ02 CICS Applid: IYDZEJ02 

Type action code then press ENTER: 

1 = General Options 

2 = Time/Date Options 

Interdependency Options 

3 = CICS Options for APIs 

4 - CICS Options for SPIs 

5 = DB2/IMS/MQ Options 

6 = Task Options 
7 = Natural Options 


Affinity Options 
8 = Affinity Options 


CICS Sysid 
Fl=Help 


CICS Applid: IYDZEJ02 
F3=Exit F4= 


TermlD: TC47 


Figure 17-1 CICS I A CINT transaction 


To set the collection for Affinity options, we much choose Option 8, which then 
displays the panel in Figure 17-2 on page 350. 
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CIU270 CICS Interdependency Analyzer for z/OS - V2R2M0 2009/06/01 

CICS Affinities Options for 09:44:56AM 

CICS Sysid : EJ02 CICS Applid : IYDZEJ02 

Modify the options and press Enter to update, or PF12 to Cancel. 

Detect affinity types: Y=Yes, N=No or blank=default 

Inter-Transaction 

ENC, DEC Y TS OUEUE Y ADDRESS CWA. . . Y 

RETRIEVE WAIT. . Y LOAD Y GETMAIN SHARED . Y 

CANCEL Y 

Transaction-System 

INGUIRE, SET . . Y ENABLE, DISABLE. Y EXTRACT. . . . . Y 

COLLECT STATS . Y PERFORM Y RESYNC Y 

WAIT Y DISCARD . . . . Y CREATE Y 

CSD Y 


CICS Sysid: EJ02 CICS Applid: IYDZEJ02 TermID: TC47 

F1= F2= F3=Exit F4= F5= F6= 

F7= F8= F9= F10= F1 1 = F12=Cancel 


Figure 17-2 Resource options panel for CICS I A 


From this panel, we can set the Affinity detection options on for both 
Inter-Transaction and Transaction System Affinities, which enables us to scope 
the amount of effort that is required to resolve any affinities. It is worth noting that 
you can resolve an affinity by making a system-related change, as opposed to an 
application-related change, for example, having to amend program code. One 
example of this is to move any queue related activity, for example, TS or TD, to a 
queue-owning region. 


17.3 Loading the DB2 database with the collected 
affinity data 

CICS Interdependency Analyzer provides you with a number of supplied jobs to 
load your collected data into the DB2 tables. The CICS IA Affinity data is loaded 
by the sample job CIUAFFLD, as shown in Example 17-1 . 

Example 1 7- 1 CICS I A CIUAFFLD sample JCL 


//CIUAFFLD JOB USER=JAMESE,NOTIFY=JAMESE, 
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CLASS=A,MSGCLASS=Y,REGION=OM 


E = IBM CICS INTERDEPENDENCIES UTILITY 
LOAD THE AFFINITY TABLES FROM AFFIN 
FILES , CIUAFF1/2/3 
AFFINITY FILES CREATED BY CICS/IA 


THE DATASET HLQ FOR DB2 SDSNLOAD 
REDTOOLS.CICSIA 

THE HLQ FOR THE CIA AFFINITY FILES. THESE FILES ARE 
CREATE AS PART OF THE CICS AFFINITIES UTILITY 


3) EDIT THE SCIUCLIS MEMBER CIUDB2BT AND CHANGE THE FOLLOWING:- * 
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Materii 


- Property of IBM 


//* "Restricted Materials of IBM" * 

//* 

II* 5697-J23 * 

II* 

II* (c) Copyright IBM Corp. 2004, 2007 All Rights Reserved. * 

II* 

II* US Government Users Restricted Rights - Use, duplication or * 

//* disclosure restricted by GSA ADP Schedule Contract with * 

II* IBM Corp. * 

II* @end_copyright@ * 

'll* 

II* CHANGE HISTORY * 

II* 

//* PN= REASON REL YYMMDD HDXIII: REMARKS * 

H* * 

II* £L0= H274130 300 040601 hdej: Date Created * 

II* £P1= 00050 300 040725 hdej: Load affiniy data tables * 

II* £P2= 00079 300 040725 hdej: Set region to OM * 

II* £P3= PK02704 300 050505 hdej: New affinity files * 

II* £P4= 00230 2100 050606 hdej: Update to CIUBTCH4 * 

II* £P5= 00244 2100 050628 hdej: Change CAU to CIU all 

II* £L6= 00235 2100 050923 hdej : Add new jobcard. 

II* £P6= 00363 2100 051003 hdej: Correct EXEC in STEPOO * 

II* £P7= 00478 2100 051026 hdjah: Add DD for SCIULODE * 

II* £L7= 00806 2200 070516 hd-nsm: Add step - total number of rows * 

II* £P8= 00822 2200 070606 hd-mxs: Add DB2 plan customization * 

//* £P7= PK72394 2200 081002 hd-ej: New update for CIU_RESOURCE * 

II* £P8= 01158 2200 081216 hd-ej: Add SYSREC06 

II* £M1= 001189 3100 090128 hdej: Remove .SDSNLOAD and. RUNLIB. LOAD* 

//********************************************************************* 

//****************************************************************** 

//JCLLIB JCLLIB 0RDER=DSN8102F. PROCLIB 

//JOBLIB DD DSN=ANTZ.CICS. IA.V31. INC38.SCIUL0AD, 

// DISP=SHR 

// DD DSN=ANTZ.CICS.IA.V31.INC38. SCIULODE, 

// DISP=SHR 

// DD DSN=SYS2.DB2.V810. SDSNLOAD, 

// DISP=SHR 

// DD DSN=DSN8102F. RUNLIB. LOAD, 

// DISP=SHR 

//********************************************************************* 

II* 

II* RUN THE BATCH PROGRAM CIUUREG 

II* - 

//STEP000 EXEC PGM=IKJEFT1B, 

// DYNAMNBR=20, 

// PARM=( 1 %C I UDB2BT ' , 1 SYS (DG2F) 1 , ' PROG (CIUUREG) ' , 

// 1 PLAN(REDIADD) ') 

II* 

II* IF YOU WISH TO UPDATE THE DATABASE WITH THE LAST USED 

//* TIME STAMP FOR EACH DB2 ROW THEN CHOOSE PARM(UPD) 
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//* — — ^-4 

//SYSPROC DD DSN=REDTOO LS.REDTST41.SC IUCLIS, 

// DISP=SHR 

//SYSUDUMP DD SYSOUT=* 

//SYSTSIN DD DUMMY 
//SYSTSPRT DD SYSOUT=* 

//SYSABOUT DD SYSOUT=* 

//SYSOUT DD SYSOUT=* 

//CIUCNTL DD DSN=REDTOOLS.CICSIA.CIUCNTL, 

// DISP=SHR 

//STEPOIO EXEC PGM=IKJEFT1B, 

// DYNAMNBR=20, 

// PARM=( 1 %C I UDB2BT ' , 1 SYS (DG2F) 1 , 1 PROG (Cl UAFFL1) 1 , 

// 1 PLAN(REDIADD) 1 , 1 PARM(UPDATE) 1 ) 

//* 1 PLAN (REDIADD) ') 

//* - 

//* IF YOU WISH TO UPDATE THE DATABASE WITH THE LAST USAGE 
//* COUNTS THEN CHOOSE PARM (UPDATE) 

//* 

//SYSPROC DD DSN=REDTOO LS.REDTST41.SC I UCLIS, 

// DISP=SHR 

//SYSUDUMP DD SYSOUT=* 

//SYSTSIN DD DUMMY 
//SYSTSPRT DD SYSOUT=* 

//SYSABOUT DD SYSOUT=* 

//SYSOUT DD SYSOUT=* 

//CIUAFF1 DD DSN=REDTOOLS.CICSIA.CIUAFFl, 

// DISP=SHR 

//CIUAFF2 DD DSN=REDT00LS.CICSIA.CIUAFF2, 

// DISP=SHR 

//CIUAFF3 DD DSN=REDT00LS.CICSIA.CIUAFF3, 

// DISP=SHR 

//CIUCNTL DD DSN=REDTOOLS.CICSIA. CIUCNTL, 

// DISP=SHR 

//* Enter ALL for all APPLIDs or the APPLID to be loaded 
//* No entry is treated the same as ALL 
//APPLID DD * 

/* 

//SYSPRINT DD SYSOUT=* 

//SYSUDUMP DD SYSOUT=* 

II* V*- — 

//* RUN SQL QUERIES FOR DB2 TABLES 

//* 

//CIUSPACE EXEC PGM=IKJEFT01 
//SYSPRINT DD SYSOUT=* 

//SYSTSPRT DD SYSOUT=* 

//SYSTSIN DD * 

DSN SYSTEM(DG2F) 

RUN PROGRAM (DSNTEP2) PLAN(DSNTEP81) PARMS( '/ALIGN (LHS) MIXED') - 
LI B ( 1 DSN8102F . RUN LI B . LOAD ' ) 

END 

/* 

//SYSIN DD DSN=REDT00LS.REDTST41.SCIUSQL(CIUSPCAF) , 
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DISP=SHR 


//* 

//* UPDATE THE CIU_RESOURCE TABLE 

//* 

//CIUUNLD EXEC PGM=IKJEFT01 
//SYSTSPRT DD SYSOUT=* 

//SYSREC DD DUMMY 
//SYSTSIN DD * 

DSN SYSTEM (DG2F) 

RUN PROGRAM (DSNTIAUL) PLAN (DSNTI B81) PARMS('SQL') - 
LIB( 1 DSN8102F. RUNLIB. LOAD 1 ) 

//SYSPRINT DD SYSOUT=* 

//SYSPUNCH DD DUMMY 
//SYSUDUMP DD SYSOUT=* 

//SYSRECOO DD DSN=&8>DATAO,DISP=(,PASS) , 

// UNIT=SYSDA,SPACE=(CYL, (200,15) ,RLSE) 

//SYSREC01 DD DSN=&&DATA1,DISP=(,PASS) , 

// UNIT=SYSDA,SPACE=(CYL, (200,15) ,RLSE) 

//SYSREC02 DD DSN=&&DATA2,DISP=(,PASS) , 

// UNIT=SYSDA,SPACE=(CYL, (200,15) ,RLSE) 

//SYSREC03 DD DSN=&&DATA3,DISP=(,PASS) , 

// UNIT=SYSDA,SPACE=(CYL, (200,15) ,RLSE) 

//SYSREC04 DD DSN=&&DATA4,DISP=(,PASS) , 

// UNIT=SYSDA,SPACE=(CYL, (200,15) ,RLSE) 

//SYSREC05 DD DSN=&&DATA5,DISP=(,PASS) , 

// UNIT=SYSDA,SPACE=(CYL, (200,15) ,RLSE) 

//SYSREC06 DD DS N =&&DATA6 ,DISP=(,PASS) , 

// UNIT=SYSDA,SPACE=(CYL, (200,15) ,RLSE) 

//SYSPUNCH DD SYSOUT=* 

//SYSIN DD DSN=REDT00LS.REDTST41.SCIUSQL(CIURSV8U) , 

// DISP=SHR 

//* 

//CIURLD EXEC DSNUPROC, 

// SYSTEM=DG2F, 

// UID= 1 CIUAFFLD 1 , 

// UTPROC=" 

//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL, (200,15) ,RLSE) 
//SORTOUT DD UNIT=SYSDA,SPACE=(CYL, (200,15) ,RLSE) 
//SORTWKOl DD UNIT=SYSDA,SPACE=(CYL, (200,15) ,RLSE) 
//SORTWK02 DD UNIT=SYSDA,SPACE=(CYL, (200,15) ,RLSE) 
//SORTWK03 DD UNIT=SYSDA,SPACE=(CYL, (200,15) ,RLSE) 
//SORTWK04 DD UNIT=SYSDA,SPACE=(CYL, (200,15) ,RLSE) 
//SORTWK05 DD UNIT=SYSDA,SPACE=(CYL, (200,15) ,RLSE) 
//SYSRECOO DD DSN=&&DATAO,DISP=(OLD, DELETE) 

// DD DSN=&&DATA1,D I SP= (OLD, DELETE) 

// DD DSN=&&DATA2,D I SP= (OLD, DELETE) 

// DD DSN=&&DATA3,DISP=(0LD, DELETE) 

// DD DSN=&&DATA4,D I SP= (OLD, DELETE) 

// DD DSN=&&DATA5, D I SP= (OLD, DELETE) 

// DD DSN=&&DATA6, D I SP= (OLD, DELETE) 

//SYSIN DD DSN=REDT00LS.REDTST41.SCIUSQL(CIURSV8L), 

// DISP=SHR 

// 
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After the data is loaded into DB2, we can then use the CICS IA plug-in to view 
the affinities that were collected. 


17.4 Using the CICS IA plug-in to identify affinities 

After we have our data loaded into DB2, we can connect using the CICS IA 
plug-in to review all of the data that was collected. When we use the CICS IA 
perspective, as a default we should be presented with a panel that is similar to 
Figure 17-3. 



Figure 1 7-3 CICS IA plug-in Supplies Samples queries 


The Supplied Samples that are available in the CICS IA plug-in are displayed. 
We are interested in the Affinities folder under the CICS samples, so we expand 
that to see what queries are predefined for us, as shown in Figure 17-4 on 
page 356. 
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Figure 1 7-4 CICS I A Supplied Sample Affinity queries 


There is one particularly useful query to run, so we highlighed it. If we run that 
query as it stands, we should be presented with a list of programs that have 
affinity statements, as shown in Figure 17-5. 


i j •Resources £3 ^ 0 Iffi <3= 

• 

All programs with potential affinities 

(10) 

Q g} PROGRAM (DRIVERP) (4) 

4 - ft? Resource Type 0 (1) 

4 ft Resource Type (PROGRAM) (1) 

4 - t Resource Type (TRANSID) (5) 

4 - 1 Resource Type (TSQUEUE AUX) (1) 
B gj PROGRAM (TST4CVD2) (1) 

4 t Resource Type (TSQUEUE AUX) (1) 

4 g} PROGRAM (WORKP) (1) 

4 t Resource Type (TSQUEUE) (1) 



Figure 17-5 All programs with potential affinities 


Now that we decided that we need to address the affinity issues, we must make 
decisions regarding the ability of the transactions to be CICSplex enabled. 

First, we must understand what resource relationships our candidate programs 
are involved with. In Figure 17-6 on page 357, we can see that program 
DRIVERP has some transactions that are associated with it and another 
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program, a TSQUEUE, and another as yet unidentified resource. If we expand 
that display, we can see the full list of resources. 



Figure 17-6 Affinities by program 


We must address all of the affinity issues that are identified here, so to begin 
with, we want to make sure that we have all of the relevant resources that are 
required for this program to run successfully within a CICSplex. This lists 
additional transactions and an additional program. We must run the same 
exercise on the additional program to make sure that we covered all possibilities. 
If we look at program WORKP, Figure 17-7 on page 358, we can see that this 
program uses a TSQUEUE also. Fortunately for us, it is the same TSQUEUE that 
our DRIVERP program uses. 
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The CICS IA collector derived this information from a running CICS region, and 
there might be some other commands that were not detected. In this case, it is 
recommended that you use the load library scanner component of CICS IA to run 
against the statically defined program to ensure that no commands were 
excluded during this exercise. 

We have two affinity issues that we must address: 

► ADDRESS CWA 

Our DRIVERP program uses the ADDRESS CWA command, and therefore 
we must examine the program further to see what type of access is used. If 
the CWA is being addressed in read-only mode, for example, to obtain the 
contents of a table, then we must ensure that the table is available to all of our 
target regions when we implement the workload. If you want to restrict write 
access to the CWA, you can specify CWAKEY=CICS, which means that CICS 
allocates the CWA from CICS-key storage, restricting application programs 
that are defined with EXECKEY(USER) to read-only access to the CWA. The 
only programs that are allowed to write to a CWA that is allocated from 
CICS-key storage are those programs that you define with EXECKEY(CICS). 

► TSQUEUE AUX 

Again, if we write to temporary storage, we must determine if there is a 
requirement for that to be read by any other program that is executing as past 
of this workload. If that is the case, we can resolve this problem by one of two 
methods: 
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- Implementing a Queue Owning Region: To define a queue as remote you 
must include an entry for the queue in a temporary storage table (TST) or 
use an appropriate TSMODEL. TS queue names are frequently generated 
dynamically, but they can also be unique fixed names. 

- Defining a Share Temporary Storage Server: By defining Temporary 
Storage pools that reside in the Coupling Facility, the queues can be 
shared across a sysplex. 


17.5 Workload management considerations 

The easiest part of workload management is setting up the definitions and 
installing them. However, it is much more complex than that because we must 
understand the current configuration and what affect our changes will have on it. 
The first part is to decide where our dynamic workload is going to run. There is 
plenty of technical material that is available to help you make those decisions, so 
we do not go into detail here, but we summarize the steps in Figure 17-8. 



Figure 17-8 Dynamic routing exploitation 


In Figure 17-8, we show (from left to right) the stages that we can go through to 
fully enable our transactions to be part of a dynamic workload. The stages are: 

1 . Existing System: This is where our transaction runs and accesses all 
resources that are local to the CICS region that the transaction(s) and 
program(s) are defined in. 
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2. Static Routing: The transaction is defined with a remote attribute of 
Dynamic=NO in our Terminal Owning Region and is defined as Local in the 
Application Owning Region. The program is not normally defined in the TOR 
and defined as Local in the AOR. There is a RemoteSystem attribute set to 
the SYSID of the AOR and, optionally, a RemoteName attribute set if you 
want to run the transaction under a different name in the AOR. 

3. Dynamic Routing Single TOR. The transaction is defined with a remote 
attribute of Dynamic=YES in our Terminal Owning Region and is defined as 
Local in the Application Owning Region. At this point, our target AORs were 
referenced by a TRANGRP definition within the Workload Management 
feature of CICSPlex SM. 


17.6 Creating the definitions for workload management 

After we decide that we have all of the relevant resources defined for our 
application, we must create definitions within CICSPlex SM so that we can 
exploit workload management. From CICS Transaction Server V3.2, the only 
method of creating and managing these definitions is through the CICSPlex SM 
Web User Interface. 

CICSPlex SM uses a routing program to process all routing requests that are 
made to it. This program, EYU9XLOP, is specified in the System Initialization 
Table parameters DSRTPGM and DTRPGM for any CICS region that wants to 
participate in dynamic transaction routing. 

Figure 17-9 on page 361 shows the elements that are required to define the 
workload management criteria for balancing, separation, and affinity processing. 
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Figure 1 7-9 Workload management mode I 


The elements are: 

TRANGRPS 

WLMDEFS 

WLMGROUP 

WLMSPEC 


These define the transactions that take place in dynamic 
routing and also their affinity relations. They are also used 
to define transactions for workload separation. 

These specify workload and separation criteria. 
TrangrpName, LUname, Userid, and Process Type. 
These are purely for administration purposes, for 
example, assigning WLMGRPS to specifications. 

These define default routing criteria, the routing algorithm 
to be used, and whether abend avoidance is activated 
(diverts workloads from a region if it is deemed to be 
unstable). The workload criteria are made known to the 
relevant regions by association of the WLMSPEC to the 
region, usually through a System Group. 


Figure 17-10 on page 362 shows Transactions in Transaction Groups. 
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Figure 17-10 Transactions in Transaction Groups 


In this group, Figure 17-10TXNGRP, we defined the six transactions that are part 
of our application. They can now be associated with target AORs by defining the 
relationship to the WLMGROUP and the WLMSPEC. 


17.7 Migrating the definitions using CICS Configuration 
Manager 


Now that we selected our application for CICSplex enablement, we must migrate 
the selected definitions from our existing single region into their target regions. If 
we look at the resources, Figure 17-1 1 on page 363, that are being used by our 
candidate application, we can then prepare them to be migrated. 
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Figure 17-11 Resources captured 

We can see that our application is going to require a number of programs, some 
mapsets, and then we have three datasets that must access from each region 
that the application runs in. Our decision on the datasets is to use a file-owning 
region so that our definitions must be migrated, which changes the attributes to 
remote. 

From this information, we can prepare a package to be migrated in CICS 
Configuration Manager. To do this, we must select the resources that are 
identified by the data that we collected in CICS Interdependency Analyzer. These 
resources are then placed into a package, ready to be migrated between differing 
environments. 

Figure 17-12 on page 364 shows the resource packaging. 
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Figure 17-12 Resource packaging 


We defined a package called NACTGRP and placed all of the required resources 
into it. We must now apply some transformation rules to the package before we 
try to migrate it. Our prime concern is that the files that we use must now be 
defined as REMOTE, so we can build a Transformation Rule to include in the 
package. 

Figure 17-13 on page 365 shows a Transformation Rule. 
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Figure 17-13 Transformation Rule 

As we migrate our resources between environments, any TSQUEUE that we find 
in the Group that has the name of OUTPUTP has its POOLNAME field changed 
to the name of the pool that it needs to reside in, which in this case is TSPOOL1 . 
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CICS Explorer resource 
manipulation scenarios 


The CICS Explorer is described as “The New Face of CICS”. One of the main 
assets of the Explorer and the plug-ins is to introduce a whole new community to 
CICS and the System z in general. Traditionally, the accepted interface to CICS 
was always through the 3270, with its ability to perform operational tasks through 
the CEMT transaction (“The Master Terminal”) and resource definition tasks 
through the CEDA transaction (“RDO - Resource Definition Online”). With the 
advent of the CICS Web User Interface, CICSPlex SM users can perform these 
tasks by an implementation of Web Services utilizing the CICSPlex SM API. 

The CICS Explorer, with its Eclipse-based environment, took this to another level 
by presenting CICS and CICSplex through a Graphical User Interface, thus 
giving it a very modern “look and feel” and enabling integration with a multitude of 
IBM Enterprise Software Portfolio products. 

In this chapter, we discuss how we can manipulate resource definitions using the 
CICS Explorer to manage some of the scenarios that typically confront us when 
supporting CICS environments. 
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18.1 Resource locking scenarios 


Resource locking is a constant factor that affects the day-to-day running of CICS 
applications all over the world. One of the best examples of locks being held on 
resources is that of the VSAM file, which has multiple users trying to update the 
same copy of a record. There are many programming techniques that are 
available today to circumvent this problem; however, they still occur on a daily 
basis. 


18.1.1 VSAM record locking 

We have an application that updates records on a VSAM file on a regular basis. 
In general, this runs satisfactorily throughout most of the day. However, a user 
calls us to say that his transaction appears to be suspended, so we must 
investigate. The initial window from the CICS Explorer shows us the transactions 
in region REDDEV41 , and it appears that our problem transaction is one of the 
the ones shown in Figure 18-1. 



Figure 18-1 Transactions suspended 
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Initially, we customize the columns so that we can see the reason for the suspend 
on each of our transactions. We do this by selecting the Customize Columns 
tab in the top right corner of the perspective, as shown in Figure 18-2. 



Figure 18-2 Customize columns 


From here, we can add SuspendType and SuspendValue so that we have a 
much more efficient view of where the problem is, which results in Figure 18-3. 



Figure 18-3 Suspend Types display 
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Now we can see that it appears that task 10401 issued some form of request 
against a dataset and is suspended with an ENQUEUE. The SuspendValue of 
FCDSRECD tells us there is a wait for a record lock in a VSAM file or 
CICS-maintained data table. If a transaction attempts to access a record that is 
locked by another transaction, it is suspended on resource type ENQUEUE until 
the lock is released. This can be a long wait because an update might depend on 
a terminal operator typing in data. Also, the suspended transaction relinquishes 
its VSAM string and, perhaps, its exclusive control of the Cl, and has to wait 
again for those resources. 

If transactions are commonly made to wait for this reason, review the 
programming logic of your applications to see if the record-locking time can be 
minimized. 

So in our case, we have an earlier task, 10378, that is running the same 
transaction. In this case, this task has a suspend type of EDF, which means that 
someone is debugging this transaction and failed to release the record lock. 
Because we must resolve the situation quickly, we PURGE the task and see if 
that sorts out the problem. By right-clicking the task, we can select the option to 
remove the task, as shown in Figure 18-4. 
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Figure 18-4 Force Purge a Task 


Before we do this, we get a confirmation window to ensure that we selected the 
right task, as shown in Figure 18-5 on page 371 . 
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REDD 

REDol 
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V Sr Task -0010378 

CEDF 

NACT IYCYTC 

| OK || Cancel | 


Figure 18-5 Confirm Force Purge 


The operational view of our tasks now shows that the task causing the wait was 
purged, Figure 18-6 on page 372, and that our suspended transaction has 
(hopefully) completed successfully. 
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Figure 18-6 Transactions resumed 


One final task we could do is to reset the columns back to their original settings, 
which we do by selecting the same drop-down list from the right corner and using 
the Reset Columns option. 


18.2 Resource state manipulation 

When connecting the CICS Explorer for the first time, the initial perspective you 
get is the System Management view, shown in Figure 18-7 on page 373. 
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Figure 18-7 CICS Explorer System management view 

From the view in Figure 18-8 on page 374, you can display all of the resources 
that are relevant to the CICS regions within the CICSplex. CICS regions can be 
individually selected just by clicking on the region name, which dynamically 
displays those details, or you can view the whole CICSplex by selecting the 
CICSplex name. 

Across the top of this perspective is a list of resources that can be displayed. The 
default view contains a number of resources, one of them being transactions, as 
shown in Figure 18-8 on page 374. 

If we select the Transactions tab, we are presented with a list of transactions 
that are defined, dependent upon the scope that is selected. In Figure 18-8 on 
page 374, we selected the CICS region REDDEV41 , to reduce the amount of 
data displayed. 
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Figure 18-8 Transaction list 


We still have a large list of transactions, so what we need to do is filter this down 
until we are presented with the transactions that we actually want to work with, 
which we do by entering the criteria in the filter window, shown in Figure 18-9. 


l£) Regions E3 % Tasks 00 ISC/MRO Connections § Terminals ffi' 1 Files % Transactions ** Name! Q X “ D 

CNX0211I Scope: REDBPLEX. Resource: CICSRGN. 10 records collected at 03-Jun-2009 15 :11:01 
Region Job Name MVSSyst... I/O Count Task Count CICS Status Release Total CPU Page In C... PageOut... 

Figure 18-9 Filter window 

Figure 18-10 on page 375 shows the resulting filter criteria. 
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Figure 18-10 Filter criteria 


If we now select the Apply Filter button, the results should display the 
transactions that we are interested in. In this case, we look for all transactions in 
CICS region REDDEV41 that begin with the characters NA. After applied, we get 
a much shorter list of transactions to work with, as shown in Figure 18-11. 



Figure 18-11 Filter criteria applied 


There is more than one method of changing the state of a particular resource. In 
our case, we want to disable one of our transactions. The quickest method of 
doing this is to select the resource in question, and then right-click, as shown in 
Figure 18-12 on page 376. 
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Figure 18-12 Disable a Transaction 


A window is displayed that offers us a number of options, and one option is to 
DISABLE the transaction. If we choose that option, we receive a confirmation 
dialog box, Figure 18-13. 



Figure 18-13 Figure 16-13 Confirm disable window 


Our transaction display should automatically refresh to display the new status of 
the transaction, as shown in Figure 18-14 on page 377. 
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Figure 18-14 Transaction disabled 


Let us assume that we inadvertently disabled the wrong transaction. We can use 
the alternative method of altering the resource to get it back into its correct state 
by double-clicking the resource in question. We disabled transaction NACT, so by 
double-clicking Figure 18-15 on page 378 is displayed. 
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Figure 18-15 Transaction Attributes 


In Figure 18-15, we scroll to the attribute that we want to change and update. In 
this instance, it is Transaction Status that we want to alter. When we select the 
attribute field, we are presented with a list of the only options that are available 
for this resource. In the case of Status, it can only be DISABLED or ENABLED, 
as shown in Figure 18-16 on page 379. 
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Figure 18-16 Transaction Status Attributes 


We select the ENABLED status and receive a confirmation message to save the 
changes. On confirming this, we should have a display of our transaction list, 
similar to Figure 18-17 on page 380. 
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Figure 18-17 Confirmation of Save Changes 


18.3 Discarding resources 

One of the abilities of the CICS Explorer is to discard resources from a running 
CICS region. The command executes under the CICS API, effectively performing 
a CEMT DISCARD command. 

The DISCARD command deletes the definition of a resource installed in the local 
CICS system, so that the system no longer has access to the resource. It 
reverses the effect of the installation of the resource, which can occur at system 
startup, through a subsequent CREATE command or CEDA transaction, by an 
automatic installation process or by a CICSPlex SM BAS command. 
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Each DISCARD command removes the definition of one resource. You can 
remove definitions for the following types of resources. 

Autoinstall models for terminals: 

► Connections 

► CorbaServer (CORBASERVER) 

► DB2Conns 

► DB2Entrys 

► DB2Trans 

► Deployed JAR files (DJAR) 

► Document templates 

► ENQ models 

► Files 

► Journals and journal models 

► LIBRARY concatenations 

► Partners 

► PIPELINES 

► Process types 

► Profiles 

► Programs, map sets, and partition sets 

► Request models 

► TCP/IP service 

► Temporary storage queue models 

► Terminals 

► Transaction classes 

► Transactions 

► Transient data queues 

► URIMAPs 

► WEBSERVICEs 

You cannot discard a resource that is currently in use, for example, you cannot 
discard a PROFILE definition if some installed TRANSACTION definition still 
points to it, or a FILE that is open, or a TRANSACTION that is scheduled for 
execution. 

In addition, some resources are not eligible for discard at all, which include 
resources whose names begin with the letters DFH (reserved for CICS-supplied 
definitions) and transactions with names that begin with C (also reserved for 
CICS). 

Some DISCARD commands cause a sync point on behalf of the issuing task, as 
the CREATE commands do. 
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DISCARD commands are recorded in the CICS catalog so that their effects 
persist over a warm or emergency restart, but they do not modify the CSD file 
and thus are lost on a cold or initial start 

If we return to our list of transactions, we can use the previous transaction, NACT, 
as our target. With the filter criteria still in place, refer to Figure 1 8-1 8 to see that 
there are two transactions in the list. 
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Figure 18-18 Transaction List 


Select the NACT transactions, and right-click it to bring up the pop-up window 
that displays our options. In this case, we DISCARD the transaction, as shown in 
Figure 18-19. 



Figure 18-19 Discard a Transaction 


When selecting the DISCARD option, you will get a confirmation window before 
you can proceed, as shown in Figure 18-20 on page 383. 


382 IBM CICS Explorer 


[0 Regions % Tasks QQ ISC/MRO Connections § Terminals dP Files % 

SS'VJfe Active Workloads 


= n’ 

CNX0211I Scope: REDDEV41. Resource: LOCTRAN. 2 records collected at 12-Jun-2009 14:29:5! 

> * (?]<■ 

Ina* 

O X v 

Region Name Status Use Count Program Priority 

Transacti... Purgeability 

Dumping 

Routing 

REDDEV41 NACP ✓ ENABLED 0 NACTCNA3 1 

DFKTCLOO NOTPURG... 

TRANDUMP 

STATIC 

REDOEV41 NACT ✓ ENABLED 0 NACTCNA1 1 

DFHTCLOO NOTPURG... 

TRANDUMP 

STATIC 



< > 

Figure 18-20 Confirm Discard window 


After you confirm your action, you are presented with the transaction list again 
minus the resource you just discarded, as shown in Figure 18-21. 
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Figure 18-21 Transaction List after Discard 


Let us assume that we made another mistake. We want to re-instate the 
transaction that we just discarded. How would we go about that? Select the 
Administration View from the toolbar. We receive a list of resource types that we 
can choose from, as shown in Figure 18-22 on page 384. 
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Figure 18-22 Administration resource options 

If we select Transaction Definitions, then we are presented with a list of 
transactions that match our criteria. The filter that we applied in the Transaction 
View perspective still applies here, so we only see our filtered list. 

By selecting the transaction that we just discarded, NACT, we now have an 
option to INSTALL it, as shown in Figure 18-23 on page 385. 
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Figure 18-23 Install transaction 


After we select the Install option, we are presented with a list of available regions 
to install it into. We choose our current region, REDDEV41, as shown in 
Figure 18-24 on page 386. 
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Figure 18-24 Region selection 


You should receive a message indicating the success of your install, as shown in 
Figure 18-25. 



1 1 1 1 

i n* 

© CNX0551I Install of TRANDEF definitions into RH30EV41 successfii 


Figure 18-25 Successful install 


Let us return to our transaction list, shown in Figure 18-26 on page 387. We 
should see that both of our transactions are now displayed. Also, if we select the 
Properties View, we can see that the Resource Signature details are updated to 
reflect the install. These attributes were introduced in CICS Transaction Server 
V4.1 . 
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As we discussed earlier, you can DISCARD a number of resources. However, 
these resources must be in an acceptable state before we can successfully 
remove them. So what happens when we try to remove a resource that is 
currently in use by the CICS region? Let us consider the case of the 
CONNECTION. What conditions must exist for the connection to be successfully 
discarded? 

The DISCARD CONNECTION command removes a CONNECTION definition 
from the local CICS system. When a connection is removed, all of the associated 
sessions also are removed. 

For deletion to be successful: 

► The connection can have no active sessions if it is remote (that is, has a 
REMOTESYSTEM value other than the name of the local region) and must 
be in OUTSERVICE status if it is not remote. 

► The interregion communications facility must be closed if the connection is an 
MRO connection. You can use the SET IRC CLOSED command to close it. 
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► If the connection is an APPC connection and the local CICS system is a 
member of a VTAM® generic resource group, there can be no deferred work 
pending. Deferred work occurs when a failure causes a unit of work, which 
used a session on the connection at SYNCLEVEL 2, to be "shunted" (held for 
later disposition because recovery action is required before disposition can be 
completed). 

Other types of connection can be discarded, even if there is recovery work 
outstanding for them; however, it is recommended that you do not discard them if 
there is. You can use the INQUIRE CONNECTION RECOVSTATUS command to 
check. 

There can be no indirect CONNECTION definitions pointing to the connection to 
be discarded. 


Note: In unusual circumstances, the discard of an LU6.1 connection can fail, 
even when it is out-of-service, if some of its sessions are still in-service. If this 
happens, set the connection status to INSERVICE, then OUTSERVICE, and 
then reissue the DISCARD command. 


CICS completes successful DISCARD CONNECTION processing with an 
implicit sync point on behalf of the issuing task, committing changes to 
recoverable resources made up to that point in the task. If the discard processing 
fails, CICS raises the INVREQ exception condition with a RESP2 value of 27, 
and does a SYNCPOINT ROLLBACK instead, rolling back changes to 
recoverable resources. For all other exception conditions, however, discard 
processing is not attempted and SYNCPOINT nor SYNCPOINT ROLLBACK is 
issued. 

So our attempt to DISCARD a CONNECTION should fail if it is in use. First, 
select a suitable connection in our current CICS region, REDDEV41 , as shown in 
Figure 18-27 on page 389. 
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Figure 18-27 Connection list 


So now let us try to DISCARD the connection. Right-click to display the pop-up 
window with all of the options available. Notice in Figure 18-28 on page 390 that 
there are many more options for this resource than there were for our 
transaction. 
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Figure 18-28 Discard a connection 

We receive a confirmation panel for the command that we are trying to execute, 
as shown in Figure 18-29 on page 391. 
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Figure 18-29 Confirm Discard connection 


This time, our DISCARD command will fail, and we should receive a message 
telling us the reason why, as shown in Figure 18-30 on page 392. 
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We receive a message in the pop-up panel telling us that our DISCARD 
command was not successfully executed, but the information bar on the 
perspective details more of the failed command. It describes the failure and 
includes the RESP and RESP2 values that were recorded. In this instance, our 
RESP code has a value of 16, which signals the INVREQ condition, and the 
RESP2 code has a value of 29, which signals that the connection is an MRO 
connection and the IRC is not closed. 
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